npm package discovery and stats viewer.

Discover Tips

  • General search

    [free text search, go nuts!]

  • Package details

    pkg:[package-name]

  • User packages

    @[username]

Sponsor

Optimize Toolset

I’ve always been into building performant and accessible sites, but lately I’ve been taking it extremely seriously. So much so that I’ve been building a tool to help me optimize and monitor the sites that I build to make sure that I’m making an attempt to offer the best experience to those who visit them. If you’re into performant, accessible and SEO friendly sites, you might like it too! You can check it out at Optimize Toolset.

About

Hi, 👋, I’m Ryan Hefner  and I built this site for me, and you! The goal of this site was to provide an easy way for me to check the stats on my npm packages, both for prioritizing issues and updates, and to give me a little kick in the pants to keep up on stuff.

As I was building it, I realized that I was actually using the tool to build the tool, and figured I might as well put this out there and hopefully others will find it to be a fast and useful way to search and browse npm packages as I have.

If you’re interested in other things I’m working on, follow me on Twitter or check out the open source projects I’ve been publishing on GitHub.

I am also working on a Twitter bot for this site to tweet the most popular, newest, random packages from npm. Please follow that account now and it will start sending out packages soon–ish.

Open Software & Tools

This site wouldn’t be possible without the immense generosity and tireless efforts from the people who make contributions to the world and share their work via open source initiatives. Thank you 🙏

© 2024 – Pkg Stats / Ryan Hefner

adonis5-swagger

v1.4.1

Published

Swagger provider for AdonisJS 5

Downloads

8,264

Readme

adonis5-swagger

Swagger, AdonisJS, SwaggerUI

typescript-image npm-image license-image

Create API documentation easily in Adonis 5 using Swagger

Table of contents

Installation

npm i --save adonis5-swagger

Compile your code:

node ace serve --watch

Connect all dependences:

node ace invoke adonis5-swagger
  • For other configuration, please update the config/swagger.ts.

Sample Usage

  • 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";
	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> {
				// User saving and returns
		}
	}
  • You can also define the schema in the Models:
		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:
    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:
/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:

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.

Build swagger spec file

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.

Swagger modes

This package support two modes:

  • PRODUCTION
  • RUNTIME

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.

Production using

For using swagger in production you should make some preparations:

  • Setup swagger config:
const swaggerConfig = { 
	mode: process.env.NODE_ENV === 'production' ? 'PRODUCTION' : 'RUNTIME',
	specFilePath: 'docs/swagger.json'
}
  • Add post hook for npm build script to your package.json:
{
	"scripts": {
		"build": "npm run compile",
		"postbuild": "node ace swagger:generate && cp -a docs/ build/docs"
	}
}
  • Deliver your source code to production server.

Swagger basic auth

Package supports auth via basic auth schema. For using auth you should add config in config/swagger.ts

import Env from '@ioc:Adonis/Core/Env'

export default {
	// ...Swagger congig
	swaggerAuth: {
		authMiddleware: 'swagger-auth',

		authCredentials: {
			login: Env.get('SWAGGER_AUTH_LOGIN'),
			password: Env.get('SWAGGER_AUTH_PASSWORD')
		}
	}
}

Register auth middleware in your start/kernel.ts

Server.middleware.registerNamed({
  'swagger-auth': 'Adonis/Addons/Swagger/AuthMiddleware',
})

That's all. Your swagger docs secured by basic auth.

Instead of using credentials, you can use function for verifying access in more complex way.

import Env from '@ioc:Adonis/Core/Env'
import { verifyDocsAccess } from 'App/Services/Auth/Docs'

export default {
	// ...Swagger congig
	swaggerAuth: {
		authMiddleware: 'swagger-auth',

		authCheck: async (login, password) => {
			return await verifyDocsAccess({ login, password })
		}
	}
}

Recipes

JWT auth for endpoints

Define JWT component inside your .yaml declaration:

components:
	securitySchemes:
		bearerAuth:            
		type: http
		scheme: bearer
		bearerFormat: JWT 

Or add to your swagger config:

export default {
	// ... config options
	options: {
		definition: {
		openapi: '3.0.0',
		info: {
			title: 'Application with swagger docs',
			version: '1.0.0',
			description: 'My application with swagger docs'
		},
		components: {
			securitySchemes: {
			bearerAuth: {
				type: "http",
				scheme: "bearer",
				bearerFormat: "JWT"
			}
			}
		}
		}
	//... config options
	}
} as SwaggerConfig

Then you can add to your controller auth security option:

@swagger
/api/users:
post:
	security:
	- bearerAuth: []