Custom Mount Paths

By default, Swagger UI is mounted at /swagger/, but you can customize this to mount it at any path you prefer. This guide shows you how to configure custom paths for both the Swagger UI and the API specification file.

Default Configuration

The simplest setup mounts Swagger UI at the default /swagger/ path:

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  
12  await pod.start();
13}

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

You can mount Swagger UI at a custom path using the mountPath parameter:

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  // Custom path - Swagger UI at /api/docs/
9  final swaggerRoute = SwaggerUIRoute(
10    Directory.current,
11    mountPath: '/api/docs/',
12  );
13  pod.webServer.addRoute(swaggerRoute, '/api/docs/**');
14  
15  await pod.start();
16}

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 parameter must end with a trailing slash (/).

Custom API Specification Path

If you want to serve the apispec.json file from a different location (e.g., at the root instead of under the mount path), you can use the customSpecPathparameter along with the ApiSpecRoute class:

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  final projectRoot = Directory.current;
8  
9  // Swagger UI at custom path, API spec at root
10  final swaggerRoute = SwaggerUIRoute(
11    projectRoot,
12    mountPath: '/api/docs/',
13    customSpecPath: '/apispec.json', // Tell Swagger UI to load from root
14  );
15  pod.webServer.addRoute(swaggerRoute, '/api/docs/**');
16  
17  // Serve apispec.json at the root
18  final apiSpecRoute = ApiSpecRoute(projectRoot);
19  pod.webServer.addRoute(apiSpecRoute, '/apispec.json');
20  
21  await pod.start();
22}

With this configuration:

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

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

  • Keep your API specification at a consistent URL regardless of where Swagger UI is mounted
  • Share the same API specification file across multiple Swagger UI instances
  • Serve the API specification separately for programmatic access

Automatic Redirection

The package automatically handles redirection from paths without trailing slashes. For example, if you access /swagger, you'll be automatically redirected to /swagger/. This ensures that relative URLs (like apispec.json) resolve correctly in the browser.

Complete Example with Multiple Configurations

Here's a complete example showing how to set up multiple Swagger UI instances with different configurations:

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  final projectRoot = Directory.current;
8  
9  // Configuration 1: Default Swagger UI at /swagger/
10  final defaultSwagger = SwaggerUIRoute(projectRoot);
11  pod.webServer.addRoute(defaultSwagger, '/swagger/**');
12  
13  // Configuration 2: Custom path with spec at root
14  final customSwagger = SwaggerUIRoute(
15    projectRoot,
16    mountPath: '/api/docs/',
17    customSpecPath: '/apispec.json',
18  );
19  pod.webServer.addRoute(customSwagger, '/api/docs/**');
20  
21  // Serve apispec.json at root for custom configuration
22  final apiSpecRoute = ApiSpecRoute(projectRoot);
23  pod.webServer.addRoute(apiSpecRoute, '/apispec.json');
24  
25  await pod.start();
26  
27  print('Swagger UI available at:');
28  print('  - http://localhost:8082/swagger/');
29  print('  - http://localhost:8082/api/docs/');
30}

Best Practices

  • Always use trailing slashes in mountPath to ensure relative paths work correctly
  • Match route patterns - if mountPath is /api/docs/, use /api/docs/** for the route pattern
  • Use ApiSpecRoute when needed - if you specify customSpecPath, make sure to add an ApiSpecRoute to serve the file at that path
  • Keep it simple - for most cases, the default configuration is sufficient

Next Steps