CLI Options

Generate an OpenAPI specification from your Serverpod endpoints using the CLI tool.

Basic Usage

dart run serverpod_swagger:generate [options]

Available Options

Option	Description	Example
`--base-url`	Sets the server URL for "Try it out" in Swagger UI	`--base-url=http://localhost:8080`
`--auth`	Authentication type: `jwt`, `apikey`, `basic`, `oauth2`	`--auth=jwt`
`--auth-description`	Custom description for the auth scheme	`--auth-description="Bearer token"`
`--secure-endpoints`	Comma-separated list of endpoints to secure (others left unsecured)	`--secure-endpoints=users,admin`
`--unsecure-endpoints`	Comma-separated list of endpoints to exclude from security	`--unsecure-endpoints=health,public`
`--secure-single-url`	Secure a single specific path	`--secure-single-url=/users/getProfile`
`--unsecure-single-url`	Unsecure a single specific path	`--unsecure-single-url=/health/check`
`--http-method`	Override the HTTP method for a specific path	`--http-method=/users/create:post`
`--unauth`	Globally disable authentication on all endpoints	`--unauth`
`--update`	Update existing `apispec.json` instead of regenerating	`--update`
`--verbose`	Show detailed output during generation	`--verbose`

Examples

Generate with JWT Auth

dart run serverpod_swagger:generate \
  --base-url=http://localhost:8080 \
  --auth=jwt

Secure Specific Endpoints Only

dart run serverpod_swagger:generate \
  --base-url=http://localhost:8080 \
  --auth=jwt \
  --secure-endpoints=users,admin \
  --unsecure-endpoints=health

Update Existing Spec

# Change base URL without regenerating
dart run serverpod_swagger:generate --update --base-url=https://api.example.com

# Add auth to existing spec
dart run serverpod_swagger:generate --update --auth=jwt

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

HTTP Method Detection

By default, HTTP methods are inferred from endpoint method names:

HTTP Method	Method Name Prefixes
`GET`	`get`, `list`, `find`, `fetch`, `search`, `count`, `check`, `has`, `is`, `exists`
`POST`	`create`, `add`, `insert`, `save`, `login`, `send`, `submit`, `upload`
`PATCH`	`update`, `modify`, `edit`, `change`, `rename`, `toggle`
`DELETE`	`delete`, `remove`, `destroy`, `clear`, `revoke`, `cancel`

Unrecognized names default to POST. Use --http-method to override.

Documentation