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 routes.

Step 1: Import the Package

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

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

Step 2: Add the Swagger UI Route

Next, add the Swagger UI route to your server's routes in the initializeServer method:

1Future<void> initializeServer() async {
2  // Initialize the server
3  await Serverpod.initialize(
4    // ... other configuration
5  );
6
7  // Create the pod
8  final pod = Serverpod(
9    // ... pod configuration
10  );
11
12  // Add the Swagger UI route
13  pod.addRoute(
14    SwaggerUIRoute(
15      apiSpecPath: '/api/openapi.json',
16      title: 'My API Documentation',
17    ),
18  );
19
20  // Start the server
21  await pod.start();
22}

This adds a route that serves the Swagger UI interface at /swagger (the default path). The Swagger UI will load the OpenAPI specification from /api/openapi.json.

Generating OpenAPI Specification

Serverpod Swagger can automatically generate an OpenAPI specification from your Serverpod endpoints. This specification is used by the Swagger UI to display your API documentation.

Step 1: Create a Generator

Create a file that will generate the OpenAPI specification. For example, create a file named generate_openapi.dart in your server's bin directory:

1import 'package:serverpod_swagger/serverpod_swagger.dart';
2import 'package:your_project_server/server.dart';
3
4Future<void> main() async {
5  // Initialize the server
6  await initializeServer();
7
8  // Generate the OpenAPI specification
9  await generateOpenAPI(
10    title: 'My API',
11    version: '1.0.0',
12    description: 'API documentation for My Project',
13    outputDirectory: 'generated',
14  );
15}

Step 2: Run the Generator

Run the generator to create the OpenAPI specification:

1dart run bin/generate_openapi.dart

This will generate an OpenAPI specification file in the generated directory.

Step 3: Serve the OpenAPI Specification

To serve the generated OpenAPI specification, add a route to your server that returns the specification file:

1import 'dart:io';
2
3class OpenAPIEndpoint extends Endpoint {
4  @override
5  Future<void> handleRequest(Session session) async {
6    // Read the OpenAPI specification file
7    final file = File('generated/openapi.json');
8    final content = await file.readAsString();
9
10    // Set the content type and return the specification
11    session.response.contentType = 'application/json';
12    session.response.write(content);
13  }
14}
15
16// In your server initialization
17pod.addEndpoint(
18  'api/openapi.json',
19  OpenAPIEndpoint(),
20);

Documenting Your Endpoints

To make your API documentation more useful, you should add documentation to your endpoints. Serverpod Swagger uses Dart documentation comments to generate the OpenAPI specification.

1/// Get user by ID
2///
3/// Returns a user by their ID
4@Route('/users/:id')
5Future<User> getUserById(Session session, int id) async {
6  // Implementation
7}
8
9/// Create a new user
10///
11/// Creates a new user with the provided information
12@Route('/users', 'POST')
13Future<User> createUser(Session session, User user) async {
14  // Implementation
15}

The first line of the documentation comment is used as the summary, and the rest is used as the description.

Accessing Swagger UI

Once you have set up Swagger UI and generated the OpenAPI specification, you can access the Swagger UI interface at http://localhost:8080/swagger (assuming your server is running on port 8080).

The Swagger UI interface allows you to browse your API documentation, see the available endpoints, and even try out the endpoints directly from the UI.

Next Steps

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

• Configure OpenAPI generation
• Customize Swagger UI options
• Add authentication to your API documentation
• Define custom schemas