Swagger UI Configuration

Serverpod Swagger allows you to customize the Swagger UI interface to match your needs. This page explains the available configuration options for the Swagger UI route.

Basic Configuration

When adding the Swagger UI route to your server, you can customize it with several options:

main.dart
1pod.webServer.addRoute(
2  SwaggerUIRoute(
3    Directory(Directory.current.path),
4    mountPath: '/swagger/',
5    apiSpecPath: 'apispec.json',
6    title: 'My API Documentation',
7    customCssUrl: '/custom/swagger.css',
8    customJsUrl: '/custom/swagger.js',
9    enableDeepLinking: true,
10    showExtensions: true,
11    showCommonExtensions: true,
12    defaultModelsExpandDepth: 1,
13    defaultModelExpandDepth: 1,
14    displayOperationId: false,
15    displayRequestDuration: true,
16    filter: true,
17    showMutatedRequest: true,
18    tryItOutEnabled: true,
19    persistAuthorization: true,
20  ),
21);

Available Options

OptionDescriptionDefault
mountPathThe base path where Swagger UI will be served/swagger/
apiSpecPathPath to the OpenAPI specification fileapispec.json
titleTitle displayed in the Swagger UISwagger UI
customCssUrlURL to a custom CSS file for styling Swagger UInull
customJsUrlURL to a custom JavaScript file for extending Swagger UInull
enableDeepLinkingIf set to true, enables deep linking for tags and operationstrue
showExtensionsControls the display of vendor extension (x-) fields and valuesfalse
showCommonExtensionsControls the display of extensions (pattern, maxLength, minLength, maximum, minimum) fields and valuesfalse
defaultModelsExpandDepthThe default expansion depth for models1
defaultModelExpandDepthThe default expansion depth for the model on the model-example section1
displayOperationIdControls the display of operationId in operations listfalse
displayRequestDurationControls the display of the request duration (in milliseconds) for Try-It-Out requestsfalse
filterIf set, enables filtering. The top bar will show an edit box that you can use to filter the tagged operations that are shownfalse
showMutatedRequestIf set, uses the mutated request returned from a requestInterceptor to produce the curl command in the UItrue
tryItOutEnabledControls whether the "Try it out" section should be enabled by defaultfalse
persistAuthorizationIf set, it persists authorization data and it would not be lost on browser close/refreshfalse

Custom CSS Styling

You can customize the appearance of Swagger UI by providing a custom CSS file. First, create a CSS file in your project's web directory:

web/custom/swagger.css
1.swagger-ui .topbar {
2  background-color: #1a365d;
3}
4
5.swagger-ui .info .title {
6  color: #2c5282;
7}
8
9.swagger-ui .opblock-tag {
10  background-color: #ebf8ff;
11}
12
13.swagger-ui .opblock.opblock-get {
14  border-color: #4299e1;
15  background-color: #ebf8ff;
16}
17
18.swagger-ui .opblock.opblock-post {
19  border-color: #48bb78;
20  background-color: #f0fff4;
21}
22
23.swagger-ui .btn.execute {
24  background-color: #2c5282;
25}

Then, reference this file in your Swagger UI route configuration:

main.dart
1pod.webServer.addRoute(
2  SwaggerUIRoute(
3    Directory(Directory.current.path),
4    mountPath: '/swagger/',
5    customCssUrl: '/custom/swagger.css',
6  ),
7);

Custom JavaScript Extensions

You can extend Swagger UI's functionality by providing a custom JavaScript file. First, create a JavaScript file in your project's web directory:

web/custom/swagger.js
1// This script will be executed after Swagger UI is initialized
2window.onload = function() {
3  // Access the Swagger UI instance
4  const ui = window.ui;
5  
6  // Add a custom authorization button
7  const authButton = document.createElement('button');
8  authButton.innerText = 'Quick Auth';
9  authButton.className = 'btn authorize';
10  authButton.onclick = function() {
11    // Set a predefined token
12    ui.preauthorizeApiKey('BearerAuth', 'YOUR_TEST_TOKEN');
13    console.log('API automatically authenticated with test token');
14  };
15  
16  // Add the button to the topbar
17  const topbar = document.querySelector('.swagger-ui .topbar');
18  if (topbar) {
19    topbar.appendChild(authButton);
20  }
21};

Then, reference this file in your Swagger UI route configuration:

main.dart
1pod.webServer.addRoute(
2  SwaggerUIRoute(
3    Directory(Directory.current.path),
4    mountPath: '/swagger/',
5    customJsUrl: '/custom/swagger.js',
6  ),
7);

Multiple Swagger UI Instances

You can add multiple Swagger UI routes to your server, each with its own configuration and API specification:

main.dart
1// Add a Swagger UI route for the public API
2pod.webServer.addRoute(
3  SwaggerUIRoute(
4    Directory(Directory.current.path),
5    mountPath: '/swagger/public/',
6    apiSpecPath: 'apispec.public.json',
7    title: 'Public API Documentation',
8  ),
9);
10
11// Add a Swagger UI route for the admin API
12pod.webServer.addRoute(
13  SwaggerUIRoute(
14    Directory(Directory.current.path),
15    mountPath: '/swagger/admin/',
16    apiSpecPath: 'apispec.admin.json',
17    title: 'Admin API Documentation',
18  ),
19);

Next Steps