Skip to main content
version 1.0.0

Documenting with Swagger

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 config/http.js file in the swagger.configurations object. And all the configurations that @fastify/swagger-ui supports can be set inside config/http.js file in the swagger.ui object:

swagger: {
    ui: {
        routePrefix: '/documentation',
    },
    configurations: {
        mode: 'dynamic',
        swagger: {
            info: {
                title: 'Athenna Swagger'
            }
        },
    }
}
warning

We highly recommend opening the config/http.js file in swagger configurations to see a little documentation of all it's options.

Basic usage​

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

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',
        properties: {
            name: { type: 'string' }
        }
    })

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

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​

In route groups you can only use the swagger method. This will set the same configuration for all routes inside the group:

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

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

Usage in route resources​

In route resources you can only use the swagger method:

// 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​

Swagger plugin is registered in your http application by default, but you can remove it setting the noSwagger as true in config/http.js file:

noSwagger: true