koa2-swagger-ui

Host swagger ui at a given directory from your koa v2 app

Inspired by:

• swagger-injector for serving on a specific route
• hapi-swaggered-ui for serving files from node_modules using a handlebars driven index.html

install

npm install koa2-swagger-ui --save

config

for more swaggerOptions see swagger-ui defaults:

1title: 'swagger', // page title
2oauthOptions: {}, // passed to initOAuth
3swaggerOptions: { // passed to SwaggerUi()
4  dom_id: 'swagger-ui-container',
5  url: 'http://petstore.swagger.io/v2/swagger.json', // link to swagger.json
6  supportedSubmitMethods: ['get', 'post', 'put', 'delete', 'patch'],
7  docExpansion: 'none',
8  jsonEditor: false,
9  defaultModelRendering: 'schema',
10  showRequestHeaders: false,
11  swaggerVersion: 'x.x.x' // read from package.json,
12  validatorUrl: null, // disable swagger-ui validator
13},
14routePrefix: '/docs', // route where the view is returned
15specPrefix: '/docs/spec', // route where the spec is returned
16exposeSpec: false, // expose spec file
17hideTopbar: false, // hide swagger top bar
18favicon: '/favicon.png', // default favicon
19customCSS: `h1 { color: red }`, // Add Custom CSS on the html

example

1import Koa from 'koa';
2import { koaSwagger } from 'koa2-swagger-ui';
3
4const app = new Koa();
5
6app.use(
7  koaSwagger({
8    routePrefix: '/swagger', // host at /swagger instead of default /docs
9    swaggerOptions: {
10      url: 'http://petstore.swagger.io/v2/swagger.json', // example path to json
11    },
12  }),
13);
14
15app.listen(3000);

example with koa-router and yaml source

depends on yamljs to turn your Yaml into a JS object

npm install --save yamljs

1const Koa = require('koa');
2const Router = require('koa-router');
3const yamljs = require('yamljs');
4const koaSwagger = require('koa2-swagger-ui');
5
6const router = new Router({ prefix: '/' });
7
8const app = new Koa();
9const router = new Router();
10
11// .load loads file from root.
12const spec = yamljs.load('./openapi.yaml');
13
14// example 1 using router.use()
15router.use(koaSwagger({ swaggerOptions: { spec } }));
16
17// example 2 using more explicit .get()
18router.get('/docs', koaSwagger({ routePrefix: false, swaggerOptions: { spec } }));
19
20app.use(router.routes());
21app.listen(3000);