Swagger UI as middleware for Koa/Express

middleware-swagger-ui

Koa/Express Midleware to serve the Swagger UI bound to your Swagger document. This acts as a living documentation for your APIs hosted from within your app.
swagger-ui version: 3.9.2

Usage

Express setup:

const express = require('express');
const app = express();
const { expressSwaggerUI } = require('middleware-swagger-ui');
const { join } = require('path');

/* Swagger UI Middleware Options */
const options = {
    title: 'Swagger UI',
    oauthOptions: false,
    swaggerOptions: {
        dom_id: '#swagger-ui',
        specFile: join(__dirname, 'path/to/your/swagger/spec'),
        layout: 'StandaloneLayout',
        deepLinking: true,
    },
    hideTopbar: false,
};

/* Serve Swagger UI */
app.use('/docs', expressSwaggerUI(options));

Options Object

• title: Page title
• oauthOptions: Passed to initOAuth()
• swaggerOptions: Passed to swaggerUI()
• swaggerOptions.url: Link to swagger specification
• swaggerOptions.specFile: Read swagger specification from local file (supports both yaml and json). Works even if swagger specification is split into multiple files. Read more here. It can resolve remote & local references (thanks to whitlockjc). NOTE: Using this property overrides url property.
• hideTopbar: Hides swagger top bar

Koa (v2) setup:

const Koa = require('koa');
const Router = require('koa-router');
const { koaSwaggerUI } = require('middleware-swagger-ui');
const app = new Koa();
const router = new Router();
const { join } = require('path');

const options = {
    title: 'Swagger UI',
    oauthOptions: false,
    swaggerOptions: {
        dom_id: '#swagger-ui',
        url: 'http://petstore.swagger.io/v2/swagger.json',
        specFile: join(__dirname, 'path/to/your/swagger/spec'),
        layout: 'StandaloneLayout',
        deepLinking: true
    },
    hideTopbar: false
};

router.get('/docs*', koaSwaggerUI(options));
app.use(router.routes()).use(router.allowedMethods());

Examples

For more examples, click here

Upcoming

• Add more tests.