Swagger

Static utility for OpenAPI v3 schema definition

Description

This static class provides a set of helper methods to assist in building and documenting RESTful APIs according to the Swagger OpenAPI v3 specification.

• At its core, it maintains a base object that reflects the OpenAPI v3 schema.

• During route registration within the starter, methods from this class are called to dynamically populate the schema in a consistent and reusable way.

• Upon application startup, two endpoints are exposed:

  • /swagger – returns the raw OpenAPI JSON schema.

  • /swagger-ui – serves the interactive Swagger UI documentation.

Usable Methods

• getIdParam(pkLabel: string = 'id'): Parameter

Returns a standard Swagger path parameter definition, commonly used for routes that require an ID (e.g., /users/:id).

Use case: Used in route definitions that include a path parameter for resource identification.

Example:

Swagger.getIdParam();        // → { name: 'id', in: 'path', required: true }
Swagger.getIdParam('slug');  // → { name: 'slug', in: 'path', required: true }

• getPaginationParams(options?: ListOptions): Parameter[]

Generates the typical pagination-related query parameters (page, pageSize, order, orderBy) used for listing endpoints.

Use case: To standardize paginated list routes and their Swagger definitions.

Example:

Swagger.getPaginationParams({
  page: 1,
  pageSize: 25,
  order: 'DESC',
  orderBy: 'createdAt'
});

Returns: An array of Swagger parameters with the specified defaults (if any).

• createSchema(props: Record<string, Schema | ParameterType>, required?: boolean): SchemaV3

Dynamically builds a Swagger schema object with given properties. Supports both full Schema objects and simple type strings like 'string', 'number', etc.

Use case: Used to define custom request/response schemas programmatically.

Example:

Swagger.createSchema({
  username: 'string',
  age: { type: 'number', minimum: 18 }
}, true);

Returns:

{
  type: 'object',
  required: true,
  properties: {
    username: { type: 'string' },
    age: { type: 'number', minimum: 18 }
  }
}

• createMultipartSchema(name: string = 'file', props?: Record<string, Schema>): SchemaV3

Creates a Swagger schema for a multipart/form-data request, commonly used for file uploads. Additional fields can be defined through props.

Use case: Used to describe endpoints that accept file uploads along with other form fields.

Example:

Swagger.createMultipartSchema('document', {
  description: { type: 'string' }
});

Returns:

{
  type: 'object',
  properties: {
    document: { type: 'string', format: 'binary' },
    description: { type: 'string' }
  }
}

Not So Usable Methods ⚠️

Those methods are thought to be used internally the library, but they can be helpful for building swagger logics without the RouterWrapper, or any other things you like.

Check those method directly in the framework as JsDoc should answer most of the questions. Those methods are:

• addSingleApiPath

• addApiPath