Adonis Swagger

Create documentation easily in Adonis 4.x using Swagger 😍

Installation

adonis install adonis-swagger

Configuration

• Register SwaggerProvider in start/app.js:

  const providers = [
    ...
    'adonis-swagger/providers/SwaggerProvider'
  ]

• Note: For projects that uses API-only blueprint (using --api-only flag), please enable Adonis/Middleware/Static under serverMiddleware in start/kernel.js:

  const serverMiddleware = [
    'Adonis/Middleware/Static',
    ...
  ]

• For other configuration, please update the config/swagger.js.

Sample Usage

• Add new route:

  Route.get('/api/hello', 'TestController.hello')

• Create TestController using adonis make:controller Test command:

  'use strict'
    
  class TestController {
    
    /**
    * @swagger
    * /api/hello:
    *   get:
    *     tags:
    *       - Test
    *     summary: Sample API
    *     parameters:
    *       - name: name
    *         description: Name of the user
    *         in: query
    *         required: false
    *         type: string
    *     responses:
    *       200:
    *         description: Send hello message
    *         example:
    *           message: Hello Guess
    */
    async hello({ request, response }) {
      const name = request.input('name', 'Guess')
      response.send({ message: 'Hello ' + name })
    }
  }
    
  module.exports = TestController

• You can also define the schema in the Models:

  'use strict'
    
  const Model = use('Model')
    
  /** 
  *  @swagger
  *  definitions:
  *    User:
  *      type: object
  *      properties:
  *        id:
  *          type: uint
  *        username:
  *          type: string
  *        email:
  *          type: string
  *        password:
  *          type: string
  *      required:
  *        - username
  *        - email
  *        - password
  */
  class User extends Model {
  }
    
  module.exports = User

• Or create a separate file containing documentation from the APIs in either JS or YAML formats, sample structure:

  project
  ├── app
  ├── config 
  ├── docs
  │   ├── controllers
  │   │   ├── **/*.js
  │   │   ├── **/*.yml
  │   └── models
  │       ├── **/*.js
  │       ├── **/*.yml

• For other sample in YAML and JS format, please refer to this link.

Open http://localhost:3333/docs in your browser, ayeey 🎉
For detail usage, please check the Swagger specification in this link.

Command List

Command | Description :-----------------------------|:----------- adonis swagger:export | Export config file & swagger-ui assets adonis swagger:export-docs | Export swagger-ui assets only adonis swagger:remove | Remove config file & swagger-ui assets adonis swagger:remove-docs | Remove swagger-ui only

Dependencies

• swagger-jsdocs
• swagger-ui-dist

Thanks

Special thanks to the creator(s) of AdonisJS for creating such a great framework.