API Reference

This page provides detailed documentation for the classes and methods available in the Serverpod Swagger package.

SwaggerUIRoute

The SwaggerUIRoute class is the main entry point for adding Swagger UI to your Serverpod server.

Constructor

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

Parameters

Parameter	Type	Description
`projectDirectory`	`Directory`	The root directory of your Serverpod project
`mountPath`	`String`	The base path where Swagger UI will be served (must end with a trailing slash)
`apiSpecPath`	`String`	Path to the OpenAPI specification file

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.

ServerpodSwaggerVersion

The ServerpodSwaggerVersion class provides version information for the Serverpod Swagger package.

Properties

Property	Type	Description
`version`	`String`	The current version of the Serverpod Swagger package

Command-line Generator

The generate.dart script in the bin directory is used to generate OpenAPI specifications from your Serverpod protocol definitions.

Usage

dart run serverpod_swagger:generate [options]

Options

Option	Description	Default
`--output`	Path to the output file	`apispec.json`
`--title`	API title	Your project name
`--description`	API description	Empty
`--version`	API version	`1.0.0`
`--server-url`	Server URL	`http://localhost:8080`
`--server-description`	Server description	Development server

Annotations

The following annotations can be used to customize the OpenAPI specification generation:

`@Route`

Specifies the route path for an endpoint. This annotation is provided by Serverpod and is used by the Swagger generator to determine the endpoint paths.

1@Route('/users/:id')
2Future<User> getUser(Session session, int id);

`@Method`

Specifies the HTTP method for an endpoint. If not provided, the method is inferred from the endpoint name.

1@Method('PATCH')
2@Route('/users/:id')
3Future<User> updateUserPartial(Session session, int id, User user);

`@Security`

Specifies the security requirements for an endpoint.

1@Security(['BearerAuth'])
2@Route('/users/profile')
3Future<User> getUserProfile(Session session);

`@Param`

Specifies the parameter name for an endpoint parameter. This is useful when the parameter name in the Dart code doesn't match the desired parameter name in the API.

1@Route('/users/search')
2Future<List<User>> searchUsers(
3  Session session,
4  @Param('query') String searchQuery,
5);

Documentation