Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/reg2005/adonis5-swagger
Swagger provider for AdonisJS 5
https://github.com/reg2005/adonis5-swagger
adonis5-swagger hacktoberfest swagger typescript
Last synced: about 1 month ago
JSON representation
Swagger provider for AdonisJS 5
- Host: GitHub
- URL: https://github.com/reg2005/adonis5-swagger
- Owner: reg2005
- License: mit
- Created: 2020-07-23T19:36:43.000Z (over 4 years ago)
- Default Branch: master
- Last Pushed: 2022-04-21T13:25:32.000Z (over 2 years ago)
- Last Synced: 2024-11-10T02:43:00.588Z (about 1 month ago)
- Topics: adonis5-swagger, hacktoberfest, swagger, typescript
- Language: TypeScript
- Homepage:
- Size: 2.27 MB
- Stars: 104
- Watchers: 3
- Forks: 7
- Open Issues: 2
-
Metadata Files:
- Readme: README.md
- Contributing: CONTRIBUTING.md
- License: LICENSE.md
Awesome Lists containing this project
- awesome-adonisjs - Adonis Swagger - Swagger for Adonis 5 (Packages)
README
# adonis5-swagger
> Swagger, AdonisJS, SwaggerUI
[![typescript-image]][typescript-url] [![npm-image]][npm-url] [![license-image]][license-url]
Create API documentation easily in Adonis 5 using [Swagger](https://swagger.io/specification/)
## Table of contents
- [Installation](#installation)
- [Sample Usage](#sample-usage)
- [Best usage](#best-usage)
- [Custom UI](#custom-ui)
- [Build swagger spec file](#build-swagger-spec-file)
- [Swagger modes](#swagger-modes)
- [Production using](#production-using)
- [Swagger basic auth](#swagger-basic-auth)
- [Recipes](#recipes)
- [JWT auth for endpoints](#jwt-auth-for-endpoints)
# Installation
```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: '[email protected]'
* 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](/sample).
Open http://localhost:3333/docs in your browser
For detail usage, please check the Swagger specification in this [SwaggerSpec](https://swagger.io/specification/)
# 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](https://preview.adonisjs.com/packages/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
window.onload = () => {
let ui = SwaggerUIBundle({
url: "{{ specUrl }}",
dom_id: "#swagger-ui",
presets: [
SwaggerUIBundle.presets.apis,
SwaggerUIBundle.SwaggerUIStandalonePreset
],
plugins: [
SwaggerUIBundle.plugins.DownloadUrl
],
})
window.ui = ui
}