Adonis AutoSwagger

You can add rich metadata to your controller actions using specific comment tags. This allows you to define summaries, tags, descriptions, and complex response/request structures.

Core Tags:

• @summary <text>: A short summary of the action.
• @tag <text>: A custom tag for grouping.
• @description <text>: A detailed description.
• @operationId <id>: A unique identifier for the operation.

Response & Request Tags:

• @responseBody <status> - <return> - <description>: Defines response bodies. <return> can be a <Schema>, <Schema[]>, or custom JSON {}.
• @requestBody <body_definition>: Defines the expected request body (e.g., <Model> or <Validator>).
• @requestFormDataBody <body_definition>: Defines request body for formData format.
• @paramPath <name> - <desc> - (meta): Defines path parameters.
• @paramQuery <name> - <desc> - (meta): Defines query parameters.
• @responseHeader <status> - <name> - <desc> - <meta>: Defines response headers.

Use JSDoc-style comments directly above your controller methods to define API operations.

Common Annotations:

• @index, @show, @update, @create: Define the operation type.
• @operationId <id>: Sets a unique operation ID.
• @description <text>: Provides a description of the endpoint.
• @summary <text>: Provides a short summary.
• @paramPath <name> - <desc> - @type(<type>) @required: Defines a path parameter. Use @type(string), @type(number), etc.
• @paramQuery <name> - <desc> - @type(<type>) @required: Defines a query parameter.
• @responseBody <status> - <schema>: Defines the response body for a specific HTTP status code. You can use model names like <Product> or include relations like <Product>.with(relations).
• @responseHeader <status> - @use(<commonKey>): Reuses a header definition from the common config section.
• @responseHeader <status> - <name> - <desc> - @example(<val>): Defines a custom response header.
• @requestBody <schema>: Defines the expected request body.
• @paramUse(<commonKey1>, <commonKey2>): Reuses common parameters defined in the config.
• @myCustomFunction: You can use custom names for operations if needed.

export default class SomeController {
  /**
   * @index
   * @operationId getProducts
   * @description Returns array of producs and it's relations
   * @responseBody 200 - <Product[]>.with(relations)
   * @paramUse(sortable, filterable)
   * @responseHeader 200 - @use(paginated)
   * @responseHeader 200 - X-pages - A description of the header - @example(test)
   */
  public async index({ request, response }: HttpContextContract) {}

  /**
   * @show
   * @paramPath id - Describe the path param - @type(string) @required
   * @paramQuery foo - Describe the query param - @type(string) @required
   * @description Returns a product with it's relation on user and user relations
   * @responseBody 200 - <Product>.with(user, user.relations)
   * @responseBody 404
   */
  public async show({ request, response }: HttpContextContract) {}
}

You can add specific Swagger metadata to your Model properties using comments. Important: These comments MUST be placed exactly 1 line above the property.

Available Annotations:

• @no-swagger: Prevents the field from being included in the schema (useful for fields where serializeAs: null isn't enough).
• @enum(val1, val2, ...): Defines an enum for the field (e.g., @enum(pending, active, deleted)).
• @format(type): Specifies a data format (e.g., uuid, email, binary).
• @example(value): Provides a specific example value for the field.
• @props({"key": "value"}): Adds additional JSON properties to the field (e.g., @props({"minLength": 10})).
• @required: Marks the field as required.

// SomeModel.ts

@column()
// @enum(pending, active, deleted)
public status: string

@column()
// @example(johndoe@example.com)
public email: string

@column()
// @props({"minLength": 10})
public age: number

@hasMany(() => ProductView)
// @no-swagger
public views: HasMany<typeof ProductView>

To generate documentation in production or CI/CD pipelines, follow these steps:

1. Create a Docs Generation Command: Create a new Ace command (e.g., commands/DocsGenerate.ts) using the provided examples from the repository (DocsGenerate.ts.example or DocsGeneratev6.ts.example).

2. Update Environment Configuration: Modify /start/env.ts to allow the DocsGenerate command to run without manual environment variable injection in CI/CD:

const isNodeAce = process.argv.some(
  (arg) => arg.endsWith("/ace") || arg === "ace"
);

export default await Env.create(
  new URL("../", import.meta.url),
  isNodeAce
    ? {}
    : {
        NODE_ENV: Env.schema.enum(["development", "production", "test"] as const),
        PORT: Env.schema.number(),
      }
);

3. Execute Generation: Run the following commands to generate the file and move it to your build folder:

node ace docs:generate
node ace build --production
cp swagger.yml build/

Note: Ensure NODE_ENV=production is set in your environment, or match the value set in your options.productionEnv configuration.

The config/swagger.ts file allows you to customize the generated documentation. Key configuration options include:

• path: The directory where the output should be placed.
• title: The title of your API documentation.
• version: The version of your API.
• tagIndex: The index used for grouping tags.
• ignore: An array of path patterns (e.g., ['/swagger', '/docs', '/v1']) to exclude from the documentation.
• common: An object used to define shared parameters and headers that can be reused across multiple endpoints using the @use annotation.

export default {
  path: __dirname + "../",
  title: "YourProject",
  version: "1.0.0",
  tagIndex: 2,
  ignore: ["/swagger", "/docs", "/v1", "/", "/something/*", "*/something"],
  common: {
    parameters: {
      sortable: [
        {
          in: "query",
          name: "sortBy",
          schema: { type: "string", example: "foo" },
        },
        {
          in: "query",
          name: "sortType",
          schema: { type: "string", example: "ASC" },
        },
      ],
    },
    headers: {
      paginated: {
        "X-Total-Pages": {
          description: "Total amount of pages",
          schema: { type: "integer", example: 5 },
        },
        "X-Total": {
          description: "Total amount of results",
          schema: { type: "integer", example: 100 },
        },
        "X-Per-Page": {
          description: "Results per page",
          schema: { type: "integer", example: 20 },
        },
      },
    },
  },
};