https://github.com/ahmadarif/adonis-swagger
Swagger provider for Adonis 4.x
https://github.com/ahmadarif/adonis-swagger
adonisjs documentation-generator documentation-tool swagger swagger-ui
Last synced: 5 months ago
JSON representation
Swagger provider for Adonis 4.x
- Host: GitHub
- URL: https://github.com/ahmadarif/adonis-swagger
- Owner: ahmadarif
- Created: 2018-03-01T04:29:15.000Z (over 8 years ago)
- Default Branch: master
- Last Pushed: 2022-12-07T17:50:04.000Z (over 3 years ago)
- Last Synced: 2025-11-23T14:07:28.065Z (7 months ago)
- Topics: adonisjs, documentation-generator, documentation-tool, swagger, swagger-ui
- Language: JavaScript
- Size: 4.52 MB
- Stars: 92
- Watchers: 3
- Forks: 28
- Open Issues: 21
-
Metadata Files:
- Readme: README.md
Awesome Lists containing this project
README
# Adonis Swagger
[](https://badge.fury.io/js/adonis-swagger)
[](https://travis-ci.org/ahmadarif/adonis-swagger)
[](https://www.npmjs.com/package/adonis-swagger)
[](https://www.npmjs.com/package/adonis-swagger)
[](https://coveralls.io/github/ahmadarif/adonis-swagger)
Create documentation easily in Adonis 4.x using [Swagger][Swagger] 😍
# Installation
```
adonis install adonis-swagger
```
# Configuration
* Register `SwaggerProvider` in `start/app.js`:
```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`:
```js
const serverMiddleware = [
'Adonis/Middleware/Static',
...
]
```
* For other configuration, please update the `config/swagger.js`.
# Sample Usage
* Add new route:
```js
Route.get('/api/hello', 'TestController.hello')
```
* Create `TestController` using `adonis make:controller Test` command:
```js
'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:
```js
'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:
```bash
project
├── app
├── config
├── docs
│ ├── controllers
│ │ ├── **/*.js
│ │ ├── **/*.yml
│ └── models
│ ├── **/*.js
│ ├── **/*.yml
```
* For other sample in YAML and JS format, please refer to this [link](/sample).
Open http://localhost:3333/docs in your browser, ayeey 🎉
For detail usage, please check the Swagger specification in this [link][SwaggerSpec].
# 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](https://www.npmjs.com/package/swagger-jsdoc)
- [swagger-ui-dist](https://www.npmjs.com/package/swagger-ui-dist)
# Thanks
Special thanks to the creator(s) of [AdonisJS][AdonisJS] for creating such a great framework.
[Swagger]:https://swagger.io/
[SwaggerSpec]:https://swagger.io/specification/
[AdonisJS]: http://adonisjs.com/