Swagger provider for AdonisJS 5
npm install adonis5-swagger[![typescript-image]][typescript-url] [![npm-image]][npm-url] [![license-image]][license-url]
Create API documentation easily in Adonis 5 using Swagger
- Installation
- Sample Usage
- Best usage
- Custom UI
- Build swagger spec file
- Swagger modes
- Production using
- Swagger basic auth
- Recipes
- JWT auth for endpoints
bash
npm i --save adonis5-swagger
`
Compile your code:
`bash
node ace serve --watch
`
Connect all dependences:
`bash
node ace invoke adonis5-swagger
`
* For other configuration, please update the config/swagger.ts.Sample Usage
* Add new route:
`js
Route.get('/api/hello', 'TestController.hello')
`* Create
TestController using node ace make:controller Test command:`js
import { HttpContextContract } from "@ioc:Adonis/Core/HttpContext";
import User from "App/Models/User"; export default class UsersController {
/**
* @swagger
* /api/users:
* post:
* tags:
* - Users
* requestBody:
* required: true
* content:
* application/json:
* description: User payload
* schema:
* type: object
* properties:
* phone:
* type: string
* example: 'James Bond'
* required: true
* email:
* type: string
* example: 'Bond007@example.com'
* required: true
* produces:
* - application/json
* responses:
* 200:
* description: Success
* content:
* application/json:
* schema:
* $ref: '#/components/schemas/User'
*/
public async create({ request, response }: HttpContextContract): Promise {
// User saving and returns
}
}
`* You can also define the schema in the Models:
`js
import {DateTime} from 'luxon'
import {BaseModel, column} from '@ioc:Adonis/Lucid/Orm' /**
* @swagger
* components:
* schemas:
* User:
* type: object
* properties:
* name:
* type: string
* email:
* type: string
*
*/
export default class User extends BaseModel {
@column({isPrimary: true})
public id: number
@column()
public name: string
@column()
public email: string
@column.dateTime({autoCreate: true})
public createdAt: DateTime
@column.dateTime({autoCreate: true, autoUpdate: true})
public updatedAt: DateTime
}
`* Or create a separate file containing documentation from the APIs in either TS or YAML formats, sample structure:
`bash
project
├── app
├── config
├── docs
│ ├── controllers
│ │ ├── */.ts
│ │ ├── */.yml
│ └── models
│ ├── */.ts
│ ├── */.yml
`
Best usage
* Create files into docs/swagger, for example docs/swagger/auth.yml may contains:`YAML
/api/auth/login:
post:
tags:
- Auth
security: []
description: Login
parameters:
- name: credentials
in: body
required: true
schema:
properties:
phone:
type: string
example: '1234567890'
required: true
produces:
- application/json
responses:
200:
description: Success
`
* You can change default settings in config/swagger.ts
* For other sample in YAML and JS format, please refer to this link.Open http://localhost:3333/docs in your browser
For detail usage, please check the Swagger specification in this SwaggerSpec
Custom UI
For using custom ui you should use own build of swagger ui. Current package contains only preconfigured and already built ui bundle. For example, you can use Adonis Edge for rendering ui with custom params.First, install edge:
`bash
npm i @adonisjs/view
`
Once installed, run the following ace command to setup the package.
`bash
node ace invoke @adonisjs/view
`
Generate new template file using Adonis generator:
`bash
node ace make:view swagger
`And then add route for custom UI:
`js
Route.get('/', async ({ view }) => {
const specUrl = 'your spec url'
return view.render('swagger', { specUrl })
})
`Your template should have similar content:
`html