Operation Object

Tags that define OpenAPI Operation Object

@autoswag

Required - Defines the HTTP method and path for an API endpoint.

Syntax

@autoswag <method> <path>

Parameters

• method - HTTP method
• path - URL path (can include path parameters with {name} syntax)

Example

/**
 * @autoswag GET /users
 */
export function listUsers() {}

/**
 * @autoswag DELETE /api/v1/users/{userId}/posts/{postId}
 * @pathParam {string} userId User ID
 * @pathParam {string} postId Post ID
 */
export function deleteUserPost() {}

Path Parameters

Include path parameters in curly braces:

/**
 * @autoswag GET /users/{id}
 * @autoswag GET /posts/{postId}/comments/{commentId}
 * @autoswag GET /files/{filePath*}  // Greedy parameter (matches /)
 */

TIP

Path parameters in the URL are automatically detected. You still need @pathParam to define their type and description.

Supported HTTP Methods

• GET
• POST
• PUT
• PATCH
• DELETE
• OPTIONS
• HEAD
• TRACE

@tag

Defines tags field

Syntax

@tag <name>

Example

Single tag:

/**
 * @autoswag GET /users
 * @tag Users
 * @response {User[]} 200 Users list
 */

Multiple tags:

/**
 * @autoswag POST /users/{id}/avatar
 * @tag Users
 * @tag Media
 * @pathParam {string} id User ID
 * @accept {File} multipart/form-data
 * @response 201 Avatar uploaded
 */

Tag Descriptions

Define tag descriptions in baseDoc:

generate({
    source: ['src/api/**/*.ts'],
    baseDoc: {
        info: { title: 'My API', version: '1.0.0' },
        tags: [
            {
                name: 'Users',
                description: 'User management endpoints',
            },
            {
                name: 'Products',
                description: 'Product catalog operations',
            },
            {
                name: 'Admin',
                description: 'Administrative functions (requires admin role)',
                externalDocs: {
                    description: 'Admin Guide',
                    url: 'https://docs.example.com/admin',
                },
            },
        ],
    },
})

@summary

Defines summary field

Syntax

@summary <text>

Example

/**
 * @autoswag GET /users
 * @summary List all users
 */

With Long Descriptions

Combine with JSDoc description:

/**
 * Retrieve detailed user information including profile, settings, and activity.
 *
 * This endpoint returns comprehensive user data. Use GET /users/{id}/profile
 * for a lighter response with just profile information.
 *
 * @autoswag GET /users/{id}
 * @summary Get user details
 * @pathParam {string} id User ID
 * @response {UserDetails} 200 Success
 */

In the generated OpenAPI:

• @summary → summary field (short, shows in lists)
• JSDoc description → description field (long, shows in detail view)

@externalDocs

Defines externalDocs field

Syntax

@externalDocs <url> [description]

Example

/**
 * @autoswag POST /payments
 * @summary Process payment
 * @accept {PaymentRequest}
 * @response {PaymentResult} 200 Payment processed
 * @externalDocs https://docs.example.com/payments
 */

/**
 * @autoswag POST /webhooks
 * @summary Receive webhook
 * @accept {WebhookPayload}
 * @response 200 Received
 * @externalDocs https://docs.example.com/webhooks Webhook setup guide
 */

@operationId

Defines operationId field

Syntax

@operationId <id>

Example

/**
 * @autoswag GET /users/{id}
 * @operationId getUserById
 */
export function getUser() {}

@deprecated

Defines deprecated field

Syntax

@deprecated

Example

/**
 * @autoswag GET /api/v1/users
 * @summary List users
 * @deprecated
 */

@security

Defines security field.

INFO

More about using security here

Syntax

@security <schemeName> [scope1 scope2 ...]

• schemeName - Name of the security scheme (defined in baseDoc)
• scopes - Optional list of required scopes (for OAuth2/OpenID Connect)

Example

/**
 * @autoswag GET /profile
 * @summary Get current user profile
 * @security bearerAuth
 * @response {User} 200 Profile data
 * @response 401 Unauthorized
 */

@server

Defines servers field

Syntax

@server <url> [description]

Example

Different server for specific endpoints:

/**
 * @autoswag POST /upload
 * @server https://cdn.example.com CDN upload endpoint
 * @accept {File} multipart/form-data
 * @response 201 Uploaded
 */

Multiple servers:

/**
 * @autoswag GET /data
 * @server https://api-primary.example.com Primary datacenter
 * @server https://api-backup.example.com Backup datacenter
 * @response {Data} 200 Success
 */