OpenAPI Generation Configuration

Serverpod Swagger automatically generates OpenAPI 3.0 specifications from your Serverpod protocol definitions. This page explains how to customize the generation process to fit your needs.

Basic Generation

The simplest way to generate the OpenAPI specification is to run the following command from your project root:

dart run serverpod_swagger:generate

This will create an apispec.json file in your project root directory with default settings.

Command-line Options

The generator supports several command-line options to customize the output:

dart run serverpod_swagger:generate [options]

Example usage:

dart run serverpod_swagger:generate --output=web/apispec.json --title="My API" --version="2.0.0" --server-url="https://api.example.com"

Customizing Endpoint Documentation

You can add documentation to your endpoints using Dart documentation comments. The generator will extract these comments and include them in the OpenAPI specification.

1/// Creates a new user in the system.
2/// 
3/// This endpoint requires admin privileges.
4/// 
5/// @param user The user to create
6/// @return The created user with ID assigned
7@Route('/users')
8Future<User> createUser(Session session, User user);

The generator will use the first line of the comment as the summary and the rest as the description. You can also use @param and @return tags to document parameters and return values.

HTTP Method Customization

By default, Serverpod Swagger assigns HTTP methods based on the endpoint name prefix:

• get* - GET
• create* - POST
• update* - PUT
• delete* - DELETE
• All others - POST

You can override this behavior by using the @Method annotation:

1@Method('PATCH')
2@Route('/users/:id')
3Future<User> updateUserPartial(Session session, int id, User user);

Custom Schema Definitions

For complex types that aren't automatically handled by the generator, you can provide custom schema definitions using YAML files.

Create a file named openapi_schemas.yaml in your project root:

1schemas:
2  CustomType:
3    type: object
4    properties:
5      id:
6        type: integer
7        format: int64
8      name:
9        type: string
10    required:
11      - id
12      - name

The generator will include these custom schema definitions in the generated OpenAPI specification.

Regenerating on Code Changes

During development, you may want to automatically regenerate the OpenAPI specification when your code changes. You can use a file watcher like watcher or build_runner to do this.

Example with watcher:

1dependencies:
2  watcher: ^1.0.0
3
4dev_dependencies:
5  build_runner: ^2.0.0

1import 'dart:io';
2import 'package:watcher/watcher.dart';
3
4void main() {
5  final watcher = DirectoryWatcher('lib/protocol');
6  watcher.events.listen((event) {
7    if (event.type == ChangeType.MODIFY && event.path.endsWith('.dart')) {
8      print('Regenerating OpenAPI spec...');
9      Process.run('dart', ['bin/generate.dart']);
10    }
11  });
12  print('Watching for changes in lib/protocol...');
13}

Run the watcher:

dart bin/watch.dart

Next Steps

• Configure Swagger UI options
• Add authentication to your API documentation