Decorators

Decorators are the core of Adonis Open Swagger's documentation generation. Apply them to your controller methods to automatically generate comprehensive OpenAPI documentation without writing a single line of manual docs.

What are Decorators?

Decorators are TypeScript annotations that add metadata to your controller methods. Adonis Open Swagger reads these decorators to understand your API's structure, parameters, responses, and security requirements—then automatically generates beautiful, interactive documentation.

Why Use Decorators?

• Intentional Documentation: Only routes with decorators are documented—keeping your docs clean and purposeful
• Type-Safe: Works seamlessly with TypeBox, Zod, and VineJS schemas for end-to-end type safety
• Single Source of Truth: Your code defines both behavior and documentation
• Zero Maintenance: Documentation updates automatically when you change decorators

Available Decorators

All decorators support TypeBox schemas, Zod schemas, VineJS schemas, and raw JSON Schema objects for maximum flexibility.

@SwaggerInfo(options)

The primary decorator that defines your endpoint's basic information. This combines tags, summary, and description in a single, convenient decorator.

Purpose: Provide high-level information about what your endpoint does, how it's categorized, and any important details.

Parameters:

• options (object):
  • tags (string[]): Categories for grouping related endpoints (e.g., ['Users', 'Authentication'])
  • summary (string): Short, one-line description of the endpoint
  • description (string, optional): Detailed explanation of the endpoint's behavior, requirements, or notes

Example Usage:

@SwaggerInfo({
  summary: "Create User",
  description: "Create a new user",
  tags: ["Users"],
})

@SwaggerParam(options, schema, required?)

Enhanced decorator for defining query parameters and path parameters with full schema validation support.

Purpose: Document URL parameters (path segments) and query string parameters with type validation and descriptions.

Parameters:

• options (object):
  • name (string): Parameter name (e.g., 'id', 'page', 'limit')
  • location (string): Location of parameter - 'query' or 'path'
  • description (string, optional): Explanation of what the parameter does
• schema (TypeBox | Zod | VineJS | JSON Schema): Validation schema defining the parameter's type and constraints
• required (boolean, optional): Whether the parameter is required (defaults to false for query params, true for path params)

Example Usage:

@SwaggerParam(
  {
    name: "userId",
    location: "path",
    description: "User ID",
  },
  vine.string(),
)

@SwaggerParam(
  {
    name: "status",
    location: "query",
    description: "Status of the User",
  },
  vine.string(),
)

@SwaggerHeader(options, schema, required?)

Decorator for defining HTTP header parameters that your endpoint expects or requires.

Purpose: Document custom headers, authentication headers, or any HTTP headers your endpoint needs.

Parameters:

• options (object):
  • name (string): Header name (e.g., 'X-API-Key', 'Authorization', 'Content-Type')
  • description (string, optional): Explanation of the header's purpose
• schema (TypeBox | Zod | VineJS | JSON Schema): Validation schema for the header value
• required (boolean, optional): Whether the header is required (defaults to false)

Example Usage:

@SwaggerHeader(
  {
    name: "X-Api-Key",
    description: "API Key for authentication",
  },
  vine.string(),
  true
)

@SwaggerResponse(status, description, schema?)

Define the structure and details of HTTP responses your endpoint can return.

Purpose: Document all possible responses (success and error cases) with their status codes, descriptions, and data structures.

Parameters:

• status (number): HTTP status code (e.g., 200, 201, 400, 404, 500)
• description (string): Explanation of when this response occurs
• schema (TypeBox | Zod | VineJS | JSON Schema, optional): Structure of the response body

Example Usage:

@SwaggerResponse(
  201,
  "User has been created.",
  vine.object({
    message: vine.string(),
  }),
)

@SwaggerRequestBody(description, schema, required?)

Define the structure and validation for request body data sent to your endpoint.

Purpose: Document POST, PUT, and PATCH request bodies with full schema validation.

Parameters:

• description (string): Explanation of what data the request body should contain
• schema (TypeBox | Zod | VineJS | JSON Schema): Validation schema for the request body structure
• required (boolean, optional): Whether the request body is required (defaults to true)

Example Usage:

@SwaggerRequestBody(
  "Create User",
  vine.object({
    full_name: vine.string(),
    email: vine.string().email(),
    password: vine.string(),
  }),
)

@SwaggerDeprecated(deprecated?)

Mark an endpoint as deprecated to warn API consumers that it will be removed in the future.

Purpose: Signal that an endpoint is outdated and should not be used in new code.

Parameters:

• deprecated (boolean, optional): Whether the endpoint is deprecated (defaults to true)

Example Usage:

@SwaggerDeprecated(true)

Best Practice: When deprecating an endpoint:

1. Add this decorator to mark it as deprecated
2. Update the @SwaggerInfo description to explain why it's deprecated
3. Provide information about the replacement endpoint
4. Set a timeline for removal

@SwaggerSecurity(security)

Define security requirements for your endpoint, such as API keys, OAuth2, or JWT authentication.

Purpose: Document authentication and authorization requirements for accessing the endpoint.

Parameters:

• security (object | object[]): Security scheme requirements. Can be a single scheme or an array of schemes.
  • Each object key is the security scheme name (defined in your OpenAPI config)
  • Each value is an array of required scopes (empty array for schemes without scopes)

Example Usage:

@SwaggerSecurity(
  {
    apiKey: [],
    oauth2: ["read", "write"],
  }
)

Common Security Schemes:

• API Key authentication
• Bearer token (JWT)
• OAuth2 with scopes
• Basic authentication

Schema Support

All decorators that accept schemas support multiple validation libraries:

Choose the schema library that best fits your project. Adonis Open Swagger automatically converts all schema types to OpenAPI-compatible JSON Schema.

Combining Decorators

You can apply multiple decorators to a single controller method to fully document your endpoint. Decorators are processed in the order they appear.

Example Usage:

@SwaggerInfo({
  summary: "Create User",
  description: "Create a new user",
  tags: ["Users"],
})
@SwaggerRequestBody(
  "Create User",
  vine.object({
    full_name: vine.string(),
    email: vine.string().email(),
    password: vine.string(),
  }),
)
@SwaggerResponse(
  201,
  "User has been created.",
  vine.object({
    message: vine.string(),
  }),
)
public async createUser() {
  // Your implementation
}

Best Practices

1. Always Use @SwaggerInfo

Every documented endpoint should have @SwaggerInfo with at least tags and a summary. This ensures your documentation is organized and searchable.

2. Document All Responses

Include @SwaggerResponse decorators for all possible responses, including error cases. This helps API consumers handle errors properly.

3. Be Specific with Descriptions

Write clear, concise descriptions that explain:

• What the endpoint does
• What parameters mean
• When different responses occur
• Any important constraints or requirements

4. Use Consistent Tags

Group related endpoints with consistent tag names (e.g., all user-related endpoints use the 'Users' tag).

5. Validate Everything

Use schema validation for all inputs (params, headers, request bodies) to ensure type safety and automatic documentation.