Getting Started

Installation

Install and configure the package using the following command :

node ace add @foadonis/openapi

Getting started

Decorate your controller

The OpenAPI schema is automatically generated using Typescript decorators. The routes of your application are automatically loaded but you might want to add some information like the description, response type, etc.

import Post from '#models/post'
import { createPostValidator } from '#validators/post'
import { ApiOperation, ApiBody, ApiResponse } from '@foadonis/openapi/decorators'
 
export default class PostsController {
  @ApiOperation({ summary: 'List all Posts' }) 
  @ApiResponse({ type: [Post] }) 
  index() {
    // ...your logic
  }
 
  @ApiOperation({ summary: 'Create a new Post' }) 
  @ApiBody({ type: () => createPostValidator }) 
  @ApiResponse({ type: Post }) 
  create() {}
}

The above decorators act as the following:

@ApiOperation():
Configures the operation. This is not required as the operations are automatically loaded from the Adonis Router.

@ApiResponse({ type: [Post] }):
Defines the response return type to be a list of Posts.

@ApiBody({ type: () => createPostValidator }):
Defines the request body schema to match the Vine compiled schema createPostValidator.

Decorate your Model

It is now time to decorate your model to configure which properties are available.

import { ApiProperty } from '@foadonis/openapi/decorators'
 
export default class Post {
  @ApiProperty() 
  declare id: number
 
  @ApiProperty() 
  declare title: string
 
  @ApiProperty() 
  declare content: string
}

Register documentation routes

Let's register the routes to access our OpenAPI documentation in start/routes.ts:

import openapi from '@foadonis/openapi/services/main'
 
openapi.registerRoutes()

Access the documentation

You can now head over your OpenAPI documentation at http://localhost:3000/api. It will welcome you with a beautiful documentation page of your api thanks to Scalar.