How Schemas Are Generated

The serverpod_swagger generator automatically creates OpenAPI schemas from your Serverpod model files and Dart endpoint signatures. This page explains how schema generation works and how you can influence the output.

Automatic Schema Generation

The generator reads two sources to build schemas:

• YAML model files in lib/src/models/ (both .yaml and .spy.yaml files) -- these produce named schemas under components/schemas.
• Dart endpoint parameters and return types -- primitive types are inlined, while references to model classes use $ref pointers.

Serverpod Model File Example

Given a standard Serverpod model file:

1class: User
2fields:
3  name: String
4  email: String
5  age: int?
6  role: String

The generator produces the following OpenAPI schema:

1{
2  "User": {
3    "type": "object",
4    "properties": {
5      "name": { "type": "string" },
6      "email": { "type": "string" },
7      "age": { "type": "integer", "format": "int64" },
8      "role": { "type": "string" }
9    },
10    "required": ["name", "email", "role"]
11  }
12}

Non-nullable fields are added to the required array. Nullable fields (ending with ?) are omitted from required.

Supported Type Mappings

Cross-Module Model Resolution

When an endpoint references a model from another Serverpod module (e.g., module:auth:UserInfo), the generator automatically locates and parses that model from the dependency's package using package_config.json.

Editing the Generated Spec

The generator writes apispec.json as a standard JSON file. You can edit it manually after generation to add custom descriptions, examples, or additional schemas. Use the --update flag on subsequent runs to apply CLI changes without overwriting your manual edits:

# First run: generate from source
dart run serverpod_swagger:generate --auth=jwt

# Later: update auth settings without regenerating
dart run serverpod_swagger:generate --update --unsecure-endpoints=public

Next Steps

• Full list of CLI generation options
• Configure authentication