SwaggerUIRoute

The SwaggerUIRoute class is the main entry point for adding Swagger UI to your Serverpod server. It handles the serving of the Swagger UI interface and the OpenAPI specification.

Overview

SwaggerUIRoute implements the RouteHandler interface from Serverpod, allowing it to be registered with your server's router to handle requests to the Swagger UI path.

Constructor

1SwaggerUIRoute(
2  Directory projectDirectory, {
3  String mountPath = '/swagger/',
4})

Parameters

ParameterTypeDescription
projectDirectoryDirectoryThe root directory of your Serverpod project. This is used to locate the OpenAPI specification file.
mountPathStringThe base path where Swagger UI will be served (must end with a trailing slash). Default is /swagger/.
apiSpecPathStringPath to the OpenAPI specification file relative to the project directory. Default is apispec.json.
titleStringTitle displayed in the Swagger UI browser tab and header. Default is Swagger UI.
customCssUrlString?URL to a custom CSS file for styling Swagger UI. If not provided, the default Swagger UI styling is used.
customJsUrlString?URL to a custom JavaScript file for extending Swagger UI functionality. If not provided, no custom JavaScript is loaded.
enableDeepLinkingboolIf set to true, enables deep linking for tags and operations. This allows direct linking to specific operations. Default is true.
showExtensionsboolControls the display of vendor extension (x-) fields and values. Default is false.
showCommonExtensionsboolControls the display of extensions (pattern, maxLength, minLength, maximum, minimum) fields and values. Default is false.
defaultModelsExpandDepthintThe default expansion depth for models in the models section. Default is 1.
defaultModelExpandDepthintThe default expansion depth for the model on the model-example section. Default is 1.
displayOperationIdboolControls the display of operationId in operations list. Default is false.
displayRequestDurationboolControls the display of the request duration (in milliseconds) for Try-It-Out requests. Default is false.
filterboolIf set, enables filtering. The top bar will show an edit box that you can use to filter the tagged operations that are shown. Default is false.
showMutatedRequestboolIf set, uses the mutated request returned from a requestInterceptor to produce the curl command in the UI. Default is true.
tryItOutEnabledboolControls whether the "Try it out" section should be enabled by default. Default is false.
persistAuthorizationboolIf set, it persists authorization data and it would not be lost on browser close/refresh. Default is false.

Methods

handleCall

1@override
2Future<bool> handleCall(HttpRequest request) async

Handles incoming HTTP requests to the Swagger UI route. This method is called by the Serverpod web server when a request is made to the configured mount path.

Parameters

ParameterTypeDescription
requestHttpRequestThe HTTP request to handle.

Returns

Returns true if the request was handled successfully, false otherwise.

Implementation Details

The handleCall method performs the following tasks:

  1. Checks if the request path matches the configured mount path.
  2. If the request is for the API specification file, serves the JSON file.
  3. If the request is for the Swagger UI, serves the HTML page with the configured options.
  4. If the request is for static assets (CSS, JavaScript, etc.), serves those files.

Usage Example

Here's an example of how to register the SwaggerUIRoute with your Serverpod server:

1import 'dart:io';
2import 'package:serverpod/serverpod.dart';
3import 'package:serverpod_swagger/serverpod_swagger.dart';
4
5class Server extends SerializationManagerServer {
6  @override
7  Future<void> initialize() async {
8    await super.initialize();
9    
10    // Register the Swagger UI route
11    router.addRoute(
12      SwaggerUIRoute(
13        Directory(Directory.current.path),
14        mountPath: '/docs/',
15        title: 'My API Documentation',
16        tryItOutEnabled: true,
17        persistAuthorization: true,
18      ),
19    );
20  }
21}

Related Documentation