Basic Usage

This guide will walk you through the basic steps to integrate Swagger UI into your Serverpod project and generate OpenAPI documentation for your endpoints.

Setting Up Swagger UI

To add Swagger UI to your Serverpod server, you need to create a route that serves the Swagger UI interface. This is done by adding a SwaggerUIRoute to your server's web server routes.

Step 1: Import the Package

First, import the Serverpod Swagger package in your server file:

server.dart
1import 'dart:io';
2import 'package:serverpod/serverpod.dart';
3import 'package:serverpod_swagger/serverpod_swagger.dart';

Step 2: Add the Swagger UI Route

Next, add the Swagger UI route to your server's web server in your main function:

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(
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}

This adds a route that serves the Swagger UI interface at /swagger/. The Swagger UI will automatically load the OpenAPI specification from /swagger/apispec.json.

Note: The mountPath parameter must end with a trailing slash.

Generating OpenAPI Specification

Serverpod Swagger can automatically generate an OpenAPI specification from your Serverpod endpoints by analyzing your endpoint classes and protocol definitions.

Step 1: Run the Generator

Run the following command from your project root to generate the OpenAPI specification:

dart run serverpod_swagger:generate

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

Step 2: Customize Generation (Optional)

You can customize the generation with command-line 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

Accessing Swagger UI

Once you have set up Swagger UI and generated the OpenAPI specification, you can access the Swagger UI interface.

  1. Start your Serverpod server
  2. Navigate to http://localhost:8082/swagger/ in your browser
  3. The Swagger UI will display your API documentation

Tip: Make sure to include the trailing slash in the URL. The route is configured to serve at /swagger/.

Live Reloading During Development

The Swagger UI route automatically re-reads the apispec.json file on every request, so you can regenerate your specification and see changes immediately by refreshing the browser.

# In one terminal: run your server
dart run bin/main.dart

# In another terminal: regenerate spec when you make changes
dart run serverpod_swagger:generate

Complete Example

Here's a complete example of a Serverpod server with Swagger UI:

bin/main.dart
1import 'dart:io';
2import 'package:serverpod/serverpod.dart';
3import 'package:serverpod_swagger/serverpod_swagger.dart';
4import 'package:my_server/server.dart';
5
6void run(List<String> args) async {
7  // Create the Serverpod instance
8  final pod = Serverpod(
9    args,
10    Protocol(),
11    Endpoints(),
12  );
13
14  // Add Swagger UI route
15  final swaggerRoute = SwaggerUIRoute(Directory.current);
16  pod.webServer.addRoute(swaggerRoute, '/swagger/**');
17
18  // Start the server
19  await pod.start();
20}

Next Steps

Now that you have set up basic Swagger UI integration, you can explore more advanced features: