Swagger UI Koa 2

Forked from swagger-ui-express

Adds middleware to your koa app to serve the Swagger UI bound to your Swagger document. This acts as living documentation for your API hosted from within your app.

Updated to Swagger 3.0.17

Usage

In app's package.json

"swagger-ui-koa": "latest" // or desired version

Setup swagger-app-wrapper.js

1import swaggerUi from 'swagger-ui-koa';
2import swaggerJSDoc from 'swagger-jsdoc';
3import convert from 'koa-convert';
4import mount from 'koa-mount';
5//import swaggerDocument from './swagger.json'; //also can be used
6
7export default function (app) {
8  //without jsdoc from swagger.json
9  //app.use(swaggerUi.serve); //serve swagger static files
10  //app.use(convert(mount('/swagger', swaggerUi.setup(swaggerDocument)))); //mount endpoint for access
11
12  //with jsdoc
13  const options = {
14    swaggerDefinition: {
15      info: {
16        title: 'API', // Title (required)
17        version: '2.0.0', // Version (required)
18      },
19    },
20    apis: [
21      './src/module/swagger/swagger.yaml',
22      './src/routes/*.js', // Path to the API docs from root
23      './src/module/swagger/parameters.yaml'
24    ],
25  };
26  // Initialize swagger-jsdoc -> returns validated swagger spec in json format
27  const swaggerSpec = swaggerJSDoc(options);
28  app.use(swaggerUi.serve); //serve swagger static files
29  app.use(convert(mount('/swagger', swaggerUi.setup(swaggerSpec)))); //mount endpoint for access
30}
31

Open http://<app_host>:<app_port>/swagger in your browser to view the documentation.

swagger-jsdoc

Swagger Explorer

By default the Swagger Explorer bar is hidden, to display it pass true as the second parameter to the setup function:

1const express = require('express');
2const app = express();
3const swaggerUi = require('swagger-ui-express');
4const swaggerDocument = require('./swagger.json');
5
6var showExplorer = true;
7  ...
8  swaggerUi.setup(swaggerDocument, showExplorer)
9  ...

Custom swagger options

To pass custom options e.g. validatorUrl, to the SwaggerUi client pass an object as the third parameter:

1
2var showExplorer = true;
3var options = {
4	validatorUrl : null
5};
6...
7swaggerUi.setup(swaggerDocument, showExplorer, options));
8...

Custom CSS styles

To customize the style of the swagger page, you can pass custom CSS as the fourth parameter.

E.g. to hide the swagger header:

1var showExplorer = false;
2var options = {};
3var customCss = '#header { display: none }';
4
5...
6swaggerUi.setup(swaggerDocument, showExplorer, options, customCss));
7...

Requirements

• Koa 2