OpenAPI Generation

The serverpod_swagger CLI analyzes your Serverpod endpoint source code using the Dart analyzer and generates an OpenAPI 3.0 specification as apispec.json in your project root.

Basic Generation

Run the generator from your Serverpod server project directory:

dart run serverpod_swagger:generate

This parses all endpoint classes in lib/src/generated/endpoints/ and model files in lib/src/models/, then writes apispec.json.

Command-Line Options

Option	Description
`--base-url=URL`	Set the server URL in the spec (default: `http://localhost:8082`)
`--auth=TYPE`	Add a security scheme: `jwt`, `apikey`, `basic`, or `oauth2`
`--auth-description=TEXT`	Custom description for the security scheme
`--secure-endpoints=LIST`	Comma-separated list of endpoints or methods to secure (e.g., `admin,user/delete`)
`--unsecure-endpoints=LIST`	Comma-separated list of endpoints or methods to leave unsecured
`--secure-single-url=PATH`	Secure a single URL path (highest priority override)
`--unsecure-single-url=PATH`	Unsecure a single URL path (highest priority override)
`--http-method=PATH:METHOD`	Override the HTTP method for a specific path (e.g., `/user/archive:delete`)
`--unauth` / `--disable-auth`	Remove all security from every endpoint
`--update`	Modify an existing `apispec.json` instead of regenerating from source
`--verbose`	Print additional details about the generated spec

Example: Full Generation with Auth

dart run serverpod_swagger:generate \
  --base-url=https://api.example.com \
  --auth=jwt \
  --unsecure-endpoints=auth/login,auth/register \
  --verbose

HTTP Method Detection

The generator infers HTTP methods from endpoint method names using prefix conventions:

HTTP Method	Name Prefixes
GET	get, list, fetch, find, read, retrieve, query, search, show, view, load, count, check, has, is, exists, lookup
POST	create, add, insert, save, register, execute, run, perform, login, send, submit, upload, import, process, trigger, start, init, generate, compute
PATCH	update, modify, patch, edit, change, set, put, replace, adjust, rename, move, toggle
DELETE	delete, remove, destroy, drop, clear, unlink, unregister, revoke, cancel, purge
POST (default)	Any method name that does not match the above prefixes

You can override any auto-detected method with the --http-method flag:

dart run serverpod_swagger:generate --http-method=/user/archive:delete

Generated Responses

Every operation in the generated spec includes three responses:

200 - Successful operation (with the return type schema, if applicable)
400 - Bad request
500 - Internal server error

Request Body Handling

For POST, PATCH, and DELETE methods, parameters are placed in a JSON request body. Non-nullable parameters are listed in the required array. For GET methods with only primitive parameters, they are placed as query parameters. If a GET method has complex (non-primitive) parameters, it falls back to POST with a request body.

Update Mode

The --update flag loads the existing apispec.json and applies only the changes specified by other flags (auth, base URL, HTTP methods) without re-analyzing the source code. This is useful for quick security or URL changes:

dart run serverpod_swagger:generate --update --base-url=https://staging.example.com

Documentation