Swagger UI Route Configuration

The SwaggerUIRoute class serves Swagger UI as a route on your Serverpod web server. It reads apispec.json from disk on every request, so changes are reflected immediately without restarting the server.

Basic Setup

server.dart
1import 'dart:io';
2import 'package:serverpod_swagger/serverpod_swagger.dart';
3
4pod.webServer.addRoute(
5  SwaggerUIRoute(
6    Directory(Directory.current.path),
7  ),
8);

With no options, Swagger UI is served at /swagger/ and loads the spec from /swagger/apispec.json.

Constructor Parameters

ParameterTypeDefaultDescription
projectRootDirectoryrequiredThe project root directory where apispec.json is located
mountPathString'/swagger/'URL path where Swagger UI is served (must end with /)
customSpecPathString?nullOverride the URL from which Swagger UI loads the spec. Defaults to mountPath + 'apispec.json'

Custom Mount Path

To serve Swagger UI at a different URL:

server.dart
1pod.webServer.addRoute(
2  SwaggerUIRoute(
3    Directory(Directory.current.path),
4    mountPath: '/docs/',
5  ),
6);

The route handles redirects automatically -- visiting /docs redirects to /docs/.

Custom Spec Path

If you want the Swagger UI to load the spec from a different URL (e.g., served by a separate route or an external URL):

server.dart
1pod.webServer.addRoute(
2  SwaggerUIRoute(
3    Directory(Directory.current.path),
4    customSpecPath: '/api/v1/spec.json',
5  ),
6);

ApiSpecRoute

The ApiSpecRoute class serves just the apispec.json file at a given path, independently of the Swagger UI. This is useful when you want to expose the raw spec at a separate URL:

server.dart
1pod.webServer.addRoute(
2  ApiSpecRoute(
3    Directory(Directory.current.path),
4  ),
5  '/apispec.json',
6);

Swagger UI Features

The served Swagger UI page includes these features enabled by default:

  • Deep linking - Share URLs to specific operations
  • Operation IDs displayed - Shows the operationId for each endpoint
  • Persist authorization - Auth tokens survive page refreshes
  • Try it out enabled - The "Try it out" button is active by default
  • Credentials included - Requests include cookies/auth headers
  • OAuth2 redirect - Configured automatically based on the mount path

The Swagger UI is loaded from the unpkg CDN (v5.18.2) and is not bundled with the package.

Note: The apispec.json file is re-read from disk on every request, so you can regenerate it while the server is running and see changes immediately in the browser.

Next Steps