Swagger Documentation

See how to create the Swagger documentation for Athenna REST API application.

Introduction

Swagger allows you to describe the structure of your APIs so that machines can read them. The ability of APIs to describe their own structure is the root of all awesomeness in Swagger.

Configuration

Athenna uses the @fastify/swagger and @fastify/swagger-ui plugins inside HttpKernel. All the configurations that @fastify/swagger supports can be set inside Path.config('http.ts') file in the swagger.configurations object. And all the configurations that @fastify/swagger-ui supports can be set inside Path.config('http.ts') file in the swagger.ui object:

Path.config('http.ts')

export default {
  swagger: {
    enabled: true,
    ui: {
      staticCSP: true,
      routePrefix: '/docs'
    },
    configurations: {
      mode: 'dynamic',
      swagger: {
        basePath: '/',
        consumes: ['application/json'],
        produces: ['application/json'],
        info: {
          title: Config.get('app.name'),
          version: Config.get('app.version'),
          description: Config.get('app.description')
        },
        externalDocs: {
          url: 'https://athenna.io',
          description: 'Find more info about Athenna here'
        },
      },
    },
  }
}

Basic usage

You can set your Swagger configurations using the Route facade in routes/http.ts file:

Path.route('http.ts')

Route.get('/hello', 'WelcomeController.show')
    .summary('Hello route')
    .tags('hello', 'world')
    .description('Hello route used to say hello to the user')
    .queryString('name', 'string', 'Name to say hello')
    .response(200, {
        description: 'Successful response',
        schema: {
            type: 'object',
            properties: {
                name: { type: 'string' }
            },
        }
    })

You can also use the swagger() method and use the same configurations of @fastify/swagger plugin:

Path.route('http.ts')

Route.get('/hello', 'WelcomeController.show').swagger({
    summary: 'Hello route',
    tags: ['hello', 'world'],
    description: 'Hello route used to say hello to the user',
    querystring: {
      type: 'object',
      properties: {
        name: {
          type: 'string',
          description: 'Name to say hello'
        }
      }
    },
    response: {
        200: {
            description: 'Successful response',
            properties: {
                name: { type: 'string' }
            }
        }
    }
})

Usage in route groups

You can also use all the swagger methods in route groups. This will set the same configuration for all routes inside the group:

Path.route('http.ts')

Route.group(() => {
    Route.get('/hello', 'WelcomeController.show').summary('Hello route')
}).swagger({...})

warning

The swagger methods of route groups will never overwrite the already set methods of routes. Use them to create "defaults" configurations for all routes such as security.

Usage in route resources

Same behavior as route groups, but for resources:

Path.route('http.ts')

// Set the same configurations for all routes of resource
Route.resource('/tests', 'WelcomeController').swagger({...})

// Set configuration only for that specific action of resource
Route.resource('/tests', 'WelcomeController').swagger('index', {...})
Route.resource('/tests', 'WelcomeController').swagger('store', {...})

Disabling Swagger

The HttpKernel class will automatically disable the plugin registration if the package does not exist, so to disable Swagger in Athenna you need to remove the @fastify/swagger and @fastify/swagger-ui packages from your application:

npm remove @fastify/swagger @fastify/swagger-ui

You can also disable by setting http.swagger.enabled to false:

Path.config('http.ts')

export default {
  swagger: {
    enabled: false
  }
}