Serverpod Swagger Examples

This page provides practical examples of how to use Serverpod Swagger in different scenarios. Each example includes code snippets and explanations to help you implement Swagger UI in your Serverpod application.

Basic Example

This example shows the minimal setup required to add Swagger UI to your Serverpod server.

main.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(
7    args,
8    Protocol(),
9    Endpoints(),
10  );
11  
12  // Add the Swagger UI route
13  final swaggerRoute = SwaggerUIRoute(Directory.current);
14  pod.webServer.addRoute(swaggerRoute, '/swagger/**');
15  
16  // Start the server
17  await pod.start();
18}

With this setup, you can access the Swagger UI at http://localhost:8082/swagger/ after generating the OpenAPI specification with dart run serverpod_swagger:generate.

Complete Server Example

This example shows a more complete server setup with multiple routes and Swagger UI.

main.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(
7    args,
8    Protocol(),
9    Endpoints(),
10  );
11  
12  // Add Swagger UI route
13  final swaggerRoute = SwaggerUIRoute(Directory.current);
14  pod.webServer.addRoute(swaggerRoute, '/swagger/**');
15  
16  // Add other routes
17  pod.webServer.addRoute(RouteRoot(), '/');
18  pod.webServer.addRoute(
19    StaticRoute.directory(Directory('static')),
20    '/*',
21  );
22  
23  // Start the server
24  await pod.start();
25}

Generating OpenAPI Specification

Basic Generation

# Generate OpenAPI specification
dart run serverpod_swagger:generate

With Custom Options

# Specify base URL
dart run serverpod_swagger:generate --base-url=http://localhost:8080

# Add authentication
dart run serverpod_swagger:generate --auth=jwt

# Customize HTTP methods
dart run serverpod_swagger:generate --http-method=users/create:post

# Update existing spec
dart run serverpod_swagger:generate --update

Authentication Example

Step 1: Generate spec with authentication

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

Step 2: Use the Swagger UI to test authenticated endpoints

After generating the spec with authentication, you can use the "Authorize" button in Swagger UI to provide your authentication token.

Custom HTTP Methods Example

By default, all endpoints use POST. You can customize HTTP methods for specific endpoints:

# Make specific endpoints use different HTTP methods
dart run serverpod_swagger:generate \
  --http-method=users/get:get \
  --http-method=users/create:post \
  --http-method=users/update:put \
  --http-method=users/delete:delete

Development Workflow

During development, you can use this workflow for live updates:

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

# Terminal 2: Regenerate spec when you make changes
dart run serverpod_swagger:generate

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

The Swagger UI route automatically re-reads the apispec.json file on every request, so you'll see your changes immediately after regenerating the spec.

More Resources

For more detailed information, check out: