Code Monkey home page Code Monkey logo

swagger-ui-koa's Introduction

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

import swaggerUi from 'swagger-ui-koa';
import swaggerJSDoc from 'swagger-jsdoc';
import convert from 'koa-convert';
import mount from 'koa-mount';
//import swaggerDocument from './swagger.json'; //also can be used

export default function (app) {
  //without jsdoc from swagger.json
  //app.use(swaggerUi.serve); //serve swagger static files
  //app.use(convert(mount('/swagger', swaggerUi.setup(swaggerDocument)))); //mount endpoint for access

  //with jsdoc
  const options = {
    swaggerDefinition: {
      info: {
        title: 'API', // Title (required)
        version: '2.0.0', // Version (required)
      },
    },
    apis: [
      './src/module/swagger/swagger.yaml',
      './src/routes/*.js', // Path to the API docs from root
      './src/module/swagger/parameters.yaml'
    ],
  };
  // Initialize swagger-jsdoc -> returns validated swagger spec in json format
  const swaggerSpec = swaggerJSDoc(options);
  app.use(swaggerUi.serve); //serve swagger static files
  app.use(convert(mount('/swagger', swaggerUi.setup(swaggerSpec)))); //mount endpoint for access
}

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

Swagger Explorer

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

const express = require('express');
const app = express();
const swaggerUi = require('swagger-ui-express');
const swaggerDocument = require('./swagger.json');

var showExplorer = true;
  ...
  swaggerUi.setup(swaggerDocument, showExplorer)
  ...

Custom swagger options

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

var showExplorer = true;
var options = {
	validatorUrl : null
};
...
swaggerUi.setup(swaggerDocument, showExplorer, options));
...

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:

var showExplorer = false;
var options = {};
var customCss = '#header { display: none }';

...
swaggerUi.setup(swaggerDocument, showExplorer, options, customCss));
...

Requirements

  • Koa 2

Recommend Projects

  • React photo React

    A declarative, efficient, and flexible JavaScript library for building user interfaces.

  • Vue.js photo Vue.js

    ๐Ÿ–– Vue.js is a progressive, incrementally-adoptable JavaScript framework for building UI on the web.

  • Typescript photo Typescript

    TypeScript is a superset of JavaScript that compiles to clean JavaScript output.

  • TensorFlow photo TensorFlow

    An Open Source Machine Learning Framework for Everyone

  • Django photo Django

    The Web framework for perfectionists with deadlines.

  • D3 photo D3

    Bring data to life with SVG, Canvas and HTML. ๐Ÿ“Š๐Ÿ“ˆ๐ŸŽ‰

Recommend Topics

  • javascript

    JavaScript (JS) is a lightweight interpreted programming language with first-class functions.

  • web

    Some thing interesting about web. New door for the world.

  • server

    A server is a program made to process requests and deliver data to clients.

  • Machine learning

    Machine learning is a way of modeling and interpreting data that allows a piece of software to respond intelligently.

  • Game

    Some thing interesting about game, make everyone happy.

Recommend Org

  • Facebook photo Facebook

    We are working to build community through open source technology. NB: members must have two-factor auth.

  • Microsoft photo Microsoft

    Open source projects and samples from Microsoft.

  • Google photo Google

    Google โค๏ธ Open Source for everyone.

  • D3 photo D3

    Data-Driven Documents codes.