Configuration

Serverpod Swagger can be configured through CLI flags when generating the OpenAPI specification, and through constructor parameters when setting up the route. This page covers all available options.

CLI Options

All configuration for the OpenAPI spec generation is done via command-line flags passed to dart run serverpod_swagger:generate.

Flag	Description
`--base-url=URL`	Set the server URL in the spec (e.g., `http://localhost:8082`)
`--auth=TYPE`	Add an authentication scheme. Supported types: `jwt`, `apikey`, `basic`, `oauth2`
`--secure-endpoints=a,b`	Comma-separated list of endpoints or paths to mark as secured (e.g., `users,admin/delete`)
`--unsecure-endpoints=a,b`	Comma-separated list of endpoints or paths to mark as unsecured
`--http-method=/path:method`	Override the HTTP method for a specific path (e.g., `--http-method=/users/getAll:get`)
`--update`	Update an existing `apispec.json` instead of regenerating from scratch
`--verbose`	Print detailed output during generation
`--unauth`	Globally remove all security from every endpoint

Authentication Examples

# JWT auth on all endpoints
dart run serverpod_swagger:generate --auth=jwt

# JWT auth, but keep login and register public
dart run serverpod_swagger:generate --auth=jwt --unsecure-endpoints=auth/login,auth/register

# API key auth, only secure admin endpoints
dart run serverpod_swagger:generate --auth=apikey --secure-endpoints=admin

# Remove all auth from an existing spec
dart run serverpod_swagger:generate --update --unauth

HTTP Method Overrides

HTTP methods are inferred from method names automatically, but you can override specific paths.

# Override a single path
dart run serverpod_swagger:generate --http-method=/users/getAll:get

# Override multiple paths
dart run serverpod_swagger:generate \
  --http-method=/users/sync:post \
  --http-method=/data/export:get

Route Configuration

The SwaggerUIRoute constructor accepts the following parameters:

SwaggerUIRoute(
  Directory projectRoot, {
  String mountPath = '/swagger/',
  String? customSpecPath,
})

projectRoot -- The directory containing apispec.json (typically Directory.current)
mountPath -- The URL path where Swagger UI is served. Must end with a trailing slash. Defaults to /swagger/
customSpecPath -- Override the URL from which Swagger UI loads the API spec. When not provided, defaults to apispec.json relative to the mount path

A separate ApiSpecRoute class is available for serving apispec.json at an independent path:

ApiSpecRoute(Directory projectRoot)

Tip: For details on custom mount paths and separating the API spec route, see the Custom Paths guide.

Programmatic API

You can also build OpenAPI specs programmatically using the exported models and functions:

example.dart

1import 'package:serverpod_swagger/serverpod_swagger.dart';
2
3final spec = SwaggerSpec();
4final endpoint = SwaggerEndpoint('greeting');
5final method = SwaggerMethod('hello');
6method.parameters['name'] = SwaggerParameter(
7  name: 'name',
8  type: 'String',
9  isNullable: false,
10);
11method.returnType = 'String';
12endpoint.methods['hello'] = method;
13spec.endpoints['greeting'] = endpoint;
14
15// Generate the OpenAPI map or JSON string
16final map = generateOpenApiMap(spec, baseUrl: 'http://localhost:8082');
17final json = generateOpenApiJson(spec, baseUrl: 'http://localhost:8082');
18
19// Infer HTTP method from a name
20final httpMethod = inferHttpMethod('getUserById'); // returns 'get'

Custom Paths - Mount Swagger UI at a custom path and serve the spec separately
Basic Usage - Step-by-step integration guide
Examples - Practical code examples

Documentation