Basic Usage

This guide walks you through integrating Swagger UI into your Serverpod project and generating an OpenAPI specification for your endpoints.

Setting Up Swagger UI

Step 1: Import the Package

server.dart

1import 'dart:io';
2import 'package:serverpod/serverpod.dart';
3import 'package:serverpod_swagger/serverpod_swagger.dart';

Step 2: Register the Swagger UI Route

Add the Swagger UI route to your server's web server. Two route registrations are required: one with the wildcard pattern for sub-paths, and one for the base path to handle the redirect.

server.dart

1void run(List<String> args) async {
2  final pod = Serverpod(
3    args,
4    Protocol(),
5    Endpoints(),
6  );
7
8  // Add the Swagger UI route
9  final swaggerRoute = SwaggerUIRoute(Directory.current);
10  pod.webServer.addRoute(swaggerRoute, '/swagger/**');
11  pod.webServer.addRoute(swaggerRoute, '/swagger');
12
13  await pod.start();
14}

This serves the Swagger UI at /swagger/. The UI automatically loads the OpenAPI specification from /swagger/apispec.json.

Note: Both route registrations are needed. /swagger/** handles sub-paths (the UI page and the spec file), while /swagger handles the redirect from /swagger to /swagger/.

Generating the OpenAPI Specification

The CLI generator analyzes your Serverpod endpoint classes and protocol model files to produce an apispec.json file.

Step 1: Run the Generator

dart run serverpod_swagger:generate

This creates an apispec.json file in your project root.

Step 2: Customize Generation (Optional)

# Specify base URL
dart run serverpod_swagger:generate --base-url=http://localhost:8082

# Add JWT authentication to all endpoints
dart run serverpod_swagger:generate --auth=jwt

# Mark specific endpoints as unsecured
dart run serverpod_swagger:generate --auth=jwt --unsecure-endpoints=status,health/check

# Override an HTTP method for a specific path
dart run serverpod_swagger:generate --http-method=/users/create:post

# Update an existing spec (preserves manual edits)
dart run serverpod_swagger:generate --update

# Show verbose output
dart run serverpod_swagger:generate --verbose

HTTP Method Inference

HTTP methods are automatically inferred from endpoint method names using naming conventions:

GET: methods starting with get, list, find, fetch, read, search, count, check, etc.
POST: methods starting with create, add, insert, save, send, etc.
PATCH: methods starting with update, edit, modify, patch, set, etc.
DELETE: methods starting with delete, remove, destroy, clear, cancel, etc.
Default: POST (for methods that do not match any convention)

You can override any inferred method using the --http-method CLI flag.

Accessing Swagger UI

Start your Serverpod server
Navigate to http://localhost:8082/swagger/ in your browser
The Swagger UI will display your API documentation

Tip: Navigating to /swagger (without trailing slash) will automatically redirect to /swagger/.

Live Reloading During Development

The Swagger UI route re-reads apispec.json from disk on every request, so you can regenerate the spec and see changes immediately by refreshing the browser.

# Terminal 1: run your server
dart run bin/main.dart

# Terminal 2: regenerate spec after making changes
dart run serverpod_swagger:generate

Documentation