Custom Mount Paths

By default, Swagger UI is mounted at /swagger/, but you can customize this to any path. You can also serve the apispec.json file at a separate location using ApiSpecRoute.

Default Configuration

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  // Default setup - Swagger UI at /swagger/
9  final swaggerRoute = SwaggerUIRoute(Directory.current);
10  pod.webServer.addRoute(swaggerRoute, '/swagger/**');
11  pod.webServer.addRoute(swaggerRoute, '/swagger');
12
13  await pod.start();
14}

With this configuration:

  • Swagger UI is available at: http://localhost:8082/swagger/
  • API spec is loaded from: http://localhost:8082/swagger/apispec.json

Custom Mount Path

Use the mountPath parameter to serve Swagger UI at a different path. Make sure the route pattern matches.

server.dart
1void run(List<String> args) async {
2  final pod = Serverpod(args, Protocol(), Endpoints());
3
4  // Swagger UI at /api/docs/
5  final swaggerRoute = SwaggerUIRoute(
6    Directory.current,
7    mountPath: '/api/docs/',
8  );
9  pod.webServer.addRoute(swaggerRoute, '/api/docs/**');
10  pod.webServer.addRoute(swaggerRoute, '/api/docs');
11
12  await pod.start();
13}

With this configuration:

  • Swagger UI is available at: http://localhost:8082/api/docs/
  • API spec is loaded from: http://localhost:8082/api/docs/apispec.json

Important: The mountPath must end with a trailing slash (/). The route pattern must include both the wildcard (/api/docs/**) and the base path (/api/docs).

Custom API Specification Path

To serve apispec.json at a different URL (e.g., at the root instead of under the mount path), use the customSpecPath parameter together with an ApiSpecRoute.

server.dart
1void run(List<String> args) async {
2  final pod = Serverpod(args, Protocol(), Endpoints());
3  final projectRoot = Directory.current;
4
5  // Swagger UI at /api/docs/, spec at /apispec.json
6  final swaggerRoute = SwaggerUIRoute(
7    projectRoot,
8    mountPath: '/api/docs/',
9    customSpecPath: '/apispec.json',
10  );
11  pod.webServer.addRoute(swaggerRoute, '/api/docs/**');
12  pod.webServer.addRoute(swaggerRoute, '/api/docs');
13
14  // Serve apispec.json at the root
15  final apiSpecRoute = ApiSpecRoute(projectRoot);
16  pod.webServer.addRoute(apiSpecRoute, '/apispec.json');
17
18  await pod.start();
19}

With this configuration:

  • Swagger UI is available at: http://localhost:8082/api/docs/
  • API spec is loaded from: http://localhost:8082/apispec.json

Why use customSpecPath? This is useful when you want to:

  • Keep the API spec at a consistent URL regardless of where Swagger UI is mounted
  • Share the same spec across multiple Swagger UI instances
  • Serve the spec separately for programmatic access by other tools

Automatic Redirection

The package automatically redirects from paths without a trailing slash to the trailing-slash version. For example, accessing /swagger redirects to /swagger/. This ensures that the relative URL apispec.json inside the HTML resolves correctly.

Best Practices

  • Always use trailing slashes in mountPath to ensure relative paths resolve correctly
  • Register both route patterns -- use /path/** for sub-paths and /path for the redirect
  • Use ApiSpecRoute when needed -- if you set customSpecPath, make sure to add an ApiSpecRoute to serve the file at that path
  • Keep it simple -- for most projects, the default configuration is sufficient

Related Pages