OpenAPI (Swagger)

Vaden supports OpenAPI (Swagger) documentation through a built-in add-on that can be enabled during project creation. This add-on generates automatic API documentation by analyzing annotations on your controllers and DTOs.

Enabling OpenAPI Support

When generating a new project using the Vaden Generator, make sure to select the OpenAPI add-on. This will create:

• Default openapi.dart configuration under lib/config/.
• Controller examples using @Api() and @ApiResponse().

tip

If you don’t enable the add-on, the documentation system won’t be available by default.

Annotating Controllers

To include a controller in the documentation, you must annotate it with @Api():

@Api(tag: 'auth', description: 'Authentication endpoints')
@Controller('/auth')
class AuthController {
  @Get('/ping')
  String ping() => 'pong';
}

If the controller is not annotated with @Api(), it will be excluded from the generated Swagger documentation.

Documenting Endpoints

Each route can be further described using @ApiOperation() and one or more @ApiResponse() annotations:

@ApiOperation(summary: 'Ping the server', description: 'Simple health check')
@ApiResponse(200, description: 'Success')
@Get('/ping')
String ping() => 'pong';

You can also specify a return schema using a DTO:

@ApiResponse(
  200,
  description: 'Successful login',
  content: ApiContent(type: 'application/json', schema: TokenResponse),
)

Security

To document security schemes, you can use the @ApiSecurity() annotation. This allows you to specify authentication methods for your endpoints.

@ApiSecurity(['bearer'])
@ApiResponse(
  200,
  description: 'Successful login',
  content: ApiContent(type: 'application/json', schema: TokenResponse),
)
@Post('/login')
Future<TokenResponse> login(@Body() LoginRequest request) async {
  // Your login logic here
}

This will add a security requirement to the generated OpenAPI spec, indicating that the endpoint requires a Bearer token for authentication.

Customizing the OpenAPI Spec

You can customize the OpenAPI spec by modifying the openapi_configuration.dart file in your lib/config/ directory. This file contains the configuration for the OpenAPI generator, including the title, version, and other metadata.

You can add a custom Security Scheme for representing JWT tokens in the OpenAPI spec. This is useful for documenting authentication methods used in your API:

@Configuration()
class OpenApiConfiguration {
  @Bean()
  OpenApi openApi(OpenApiConfig config) {
    return OpenApi(
      version: '3.0.0',
      info: Info(
        title: 'Vaden API',
        version: '1.0.0',
        description: 'Vaden Backend example',
      ),
      servers: [
        config.localServer,
      ],
      tags: config.tags,
      paths: config.paths,
      components: Components(
        schemas: config.schemas,
        securitySchemes: {
          'bearer': SecurityScheme.http(
            scheme: HttpSecurityScheme.bearer,
            bearerFormat: 'JWT',
            description: 'Bearer token for authentication',
          ),
        },
      ),
    );
  }

Serving the Documentation

Once enabled, your project will expose:

• /docs/openapi.json – The raw OpenAPI spec.
• /docs/ – Swagger UI rendered via static resources.

You don’t need to configure these manually — they’re included with the add-on and mounted automatically.