Examples

Practical examples of how to use Serverpod Swagger in different scenarios.

Minimal Setup

The simplest possible integration -- register the route and generate the spec.

server.dart

1import 'dart:io';
2import 'package:serverpod/serverpod.dart';
3import 'package:serverpod_swagger/serverpod_swagger.dart';
4
5void run(List<String> args) async {
6  final pod = Serverpod(args, Protocol(), Endpoints());
7
8  final swaggerRoute = SwaggerUIRoute(Directory.current);
9  pod.webServer.addRoute(swaggerRoute, '/swagger/**');
10  pod.webServer.addRoute(swaggerRoute, '/swagger');
11
12  await pod.start();
13}

dart run serverpod_swagger:generate

Access the Swagger UI at http://localhost:8082/swagger/.

Generation with Authentication

Add JWT authentication to all endpoints, then exclude specific public ones.

# JWT auth on all endpoints, except login and register
dart run serverpod_swagger:generate \
  --base-url=http://localhost:8082 \
  --auth=jwt \
  --unsecure-endpoints=auth/login,auth/register

After generating, use the "Authorize" button in Swagger UI to enter your JWT token.

Other Auth Types

# API key auth
dart run serverpod_swagger:generate --auth=apikey

# Basic auth
dart run serverpod_swagger:generate --auth=basic

# OAuth2
dart run serverpod_swagger:generate --auth=oauth2 --base-url=http://localhost:8082

HTTP Method Inference

HTTP methods are inferred automatically from your endpoint method names. Given an endpoint like this:

user_endpoint.dart

1class UserEndpoint extends Endpoint {
2  Future<List<User>> listUsers(Session session) async { ... }
3  Future<User> getUser(Session session, int id) async { ... }
4  Future<User> createUser(Session session, String name) async { ... }
5  Future<User> updateUser(Session session, int id, String name) async { ... }
6  Future<void> deleteUser(Session session, int id) async { ... }
7  Future<bool> doSomething(Session session) async { ... }
8}

The generator will produce:

GET /user/listUsers
GET /user/getUser
POST /user/createUser
PATCH /user/updateUser
DELETE /user/deleteUser
POST /user/doSomething (default for unrecognized names)

Overriding Inferred Methods

# Override specific paths
dart run serverpod_swagger:generate \
  --http-method=/user/doSomething:get \
  --http-method=/user/updateUser:put

Updating an Existing Spec

Use --update to modify an existing apispec.json without regenerating from source. This is useful for changing auth or base URL on an already-generated spec.

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

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

# Remove all auth
dart run serverpod_swagger:generate --update --unauth

Programmatic API

Build an OpenAPI spec in code without running the CLI.

programmatic_example.dart

1import 'package:serverpod_swagger/serverpod_swagger.dart';
2
3final spec = SwaggerSpec();
4
5// Define an endpoint
6final endpoint = SwaggerEndpoint('greeting');
7final method = SwaggerMethod('sayHello');
8method.parameters['name'] = SwaggerParameter(
9  name: 'name',
10  type: 'String',
11  isNullable: false,
12);
13method.returnType = 'String';
14endpoint.methods['sayHello'] = method;
15spec.endpoints['greeting'] = endpoint;
16
17// Generate the OpenAPI map
18final openApiMap = generateOpenApiMap(
19  spec,
20  baseUrl: 'http://localhost:8082',
21);
22
23// Or generate a JSON string directly
24final jsonString = generateOpenApiJson(
25  spec,
26  baseUrl: 'http://localhost:8082',
27);
28
29// Utility: infer HTTP method from a name
30print(inferHttpMethod('getUser'));    // 'get'
31print(inferHttpMethod('createUser')); // 'post'
32print(inferHttpMethod('updateUser')); // 'patch'
33print(inferHttpMethod('deleteUser')); // 'delete'
34print(inferHttpMethod('doStuff'));    // 'post' (default)

Development Workflow

# Terminal 1: run your server
dart run bin/main.dart

# Terminal 2: regenerate spec after making changes
dart run serverpod_swagger:generate

# Then refresh your browser at http://localhost:8082/swagger/

The Swagger UI route re-reads apispec.json from disk on every request with no-cache headers, so you see changes immediately after regenerating.

Documentation