adonis5-swagger
Advanced tools
Swagger, AdonisJS, SwaggerUI
Create API documentation easily in Adonis 5 using Swagger
npm i --save adonis5-swagger
Compile your code:
node ace serve --watch
Connect all dependences:
node ace invoke adonis5-swagger
config/swagger.ts.Add new route:
Route.get('/api/hello', 'TestController.hello')
Create TestController using node ace make:controller Test command:
import { HttpContextContract } from '@ioc:Adonis/Core/HttpContext'
export default 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
*/
public async hello({ request, response }: HttpContextContract) {
const name = request.input('name', 'Guess')
return response.send({ message: 'Hello ' + name })
}
}
You can also define the schema in the Models:
import { BaseModel } from '@ioc:Adonis/Lucid/Orm'
/**
* @swagger
* definitions:
* User:
* type: object
* properties:
* id:
* type: uint
* username:
* type: string
* email:
* type: string
* password:
* type: string
* required:
* - username
* - email
* - password
*/
export default class User extends BaseModel {
}
Or create a separate file containing documentation from the APIs in either TS or YAML formats, sample structure:
project
├── app
├── config
├── docs
│ ├── controllers
│ │ ├── **/*.ts
│ │ ├── **/*.yml
│ └── models
│ ├── **/*.ts
│ ├── **/*.yml
/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
Open http://localhost:3333/docs in your browser For detail usage, please check the Swagger specification in this SwaggerSpec
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:
npm i @adonisjs/view
Once installed, run the following ace command to setup the package.
node ace invoke @adonisjs/view
Generate new template file using Adonis generator:
node ace make:view swagger
And then add route for custom UI:
Route.get('/', async ({ view }) => {
const specUrl = 'your spec url'
return view.render('swagger', { specUrl })
})
Your template should have similar content:
<!DOCTYPE html>
<head>
<script src="//unpkg.com/swagger-ui-dist@3/swagger-ui-standalone-preset.js"></script>
<script src="//unpkg.com/swagger-ui-dist@3/swagger-ui-bundle.js"></script>
<link rel="stylesheet" href="//unpkg.com/swagger-ui-dist@3/swagger-ui.css"/>
<script>
window.onload = () => {
let ui = SwaggerUIBundle({
url: "{{ specUrl }}",
dom_id: "#swagger-ui",
presets: [
SwaggerUIBundle.presets.apis,
SwaggerUIBundle.SwaggerUIStandalonePreset
],
plugins: [
SwaggerUIBundle.plugins.DownloadUrl
],
})
window.ui = ui
}
</script>
</head>
<body>
<div id="swagger-ui"></div>
</body>
</html>
It is the simplest way for using custom swagger ui, but of course you could use Webpack or another bundler tool for bundling your pre configured Swagger ui.
You can build swagger spec file the next way:
Set specFilePath option to your swagger config:
const swaggerConfig = {
specFilePath: 'docs/swagger.json'
}
And then run adonis command:
node ace swagger:generate
Generated file will be written to by path configured in config.
This package support two modes:
By default RUNTIME mode enabled. When RUNTIME mode enabled package rebuild swagger spec file on each request. When you use PRODUCTION you should build your swagger spec once and then package will be respond this file content on each request.
For using swagger in production you should make some preparations:
const swaggerConfig = {
mode: process.env.NODE_ENV === 'production' ? 'PRODUCTION' : 'RUNTIME',
specFilePath: 'docs/swagger.json'
}
package.json:{
"scripts": {
"build": "npm run compile",
"postbuild": "node ace swagger:generate && cp -a docs/ build/docs"
}
}
FAQs
Swagger provider for AdonisJS 5
The npm package adonis5-swagger receives a total of 985 weekly downloads. As such, adonis5-swagger popularity was classified as not popular.
We found that adonis5-swagger demonstrated a not healthy version release cadence and project activity because the last version was released a year ago. It has 1 open source maintainer collaborating on the project.
Did you know?
Socket for GitHub automatically highlights issues in each pull request and monitors the health of all your open source dependencies. Discover the contents of your packages and block harmful activity before you install or update your dependencies.
Security News
OpenSSF has published OSPS Baseline, an initiative designed to establish a minimum set of security-related best practices for open source software projects.
Security News
Michigan TypeScript founder Dimitri Mitropoulos implements WebAssembly runtime in TypeScript types, enabling Doom to run after processing 177 terabytes of type definitions.
Security News
vlt's new "reproduce" tool verifies npm packages against their source code, outperforming traditional provenance adoption in the JavaScript ecosystem.