Document your API

The OpenApi Plugin allows you to, through decorators, document your API endpoints and generate an OpenAPI specification. This specification can be used to create interactive API documentation, client SDKs, and more.

The plugin uses 3 decorators to document your API endpoints.

The plugin uses the HTTP Plugin decorator to extract information about the API endpoints. Make sure to use the HTTP Plugin decorators to define your API routes before using the OpenApi decorators.

@OpenApiResponse

It allows you to define the response for an API endpoint. You can specify the status code, description, and schema of the response.

@Controller()
export class ExampleController {
    ...

    @Get()
    @OpenApiResponse({ statusCode: 200, type: 'array', items: [{ type: Any }], description: 'Returns a list of objects' })
    get() {...}

    // You can also define multiple responses for an endpoint by using the `@OpenApiResponse` decorator multiple times.
    @Put(':index')
    @OpenApiResponse({ statusCode: 200, type: Any, description: 'Updates an object by index' })
    @OpenApiResponse({ statusCode: 404, description: 'Object not found' })
    @OpenApiResponse({ statusCode: 400, description: 'Bad request' })
    put(@Path('index') index: string, @Body() updated: Any) {...}

    ...
}

Please, check the API reference for more information about the @OpenApiResponse decorator and its options.

AxiSpark.js only allows you to define classes as response schemas. TypeScript have a limitation that prevents you from using interfaces as response schemas.

@OpenApiSchema

Allows you to define a schema for your API endpoint. You can specify some properties of the schema. It also allows you to define properties for the schema, using the @OpenApiProperty decorator. The @OpenApiSchema decorator is flexible and can be used to define schemas for request bodies, response bodies, etc. It can also be used to define schemas for complex objects, such as arrays and nested objects.

@OpenApiSchema()
export class Entity {
    ...
}

@OpenApiSchema({ description: 'Extra information for the Todo item', example: { description: 'This is a sample task', completed: false } })
export class Todo {
    ...
}

Please, check the API reference for more information about the @OpenApiSchema decorator and its options.

@OpenApiProperty

Allows you to define properties for your API schemas. You can specify the type, description, and other attributes of each property.

@OpenApiSchema()
export class Todo {
    @OpenApiProperty()
    index: number;

    @OpenApiProperty({
        name: 'Task',
        type: 'string',
        default: 'New Task',
        description: 'The task to be done',
        maxLength: 100,
        minLength: 1,
        pattern: '^[a-zA-Z0-9 ]+$'
    })
    task: string;

    @OpenApiProperty()
    todo?: TodoExtra;
}

@OpenApiSchema({ description: 'Extra information for the Todo item', example: { description: 'This is a sample task', completed: false } })
export class TodoExtra {
    @OpenApiProperty({
        name: 'Description',
        type: 'string',
        default: 'No description',
        description: 'The description of the task',
        maxLength: 200,
        minLength: 1,
        pattern: '^[a-zA-Z0-9 ]+$'
    })
    description: string;

    @OpenApiProperty({ name: 'Completed', type: 'boolean', default: false, description: 'Whether the task is completed or not' })
    completed: boolean;
}

Please, check the API reference for more information about the @OpenApiProperty decorator and its options.