https://github.com/vivek-26/middleware-swagger-ui
Adds middleware to your Koa/Express App to serve the Swagger UI bound to your Swagger document. This acts as a living documentation for your APIs hosted from within your App.
https://github.com/vivek-26/middleware-swagger-ui
commitizen express-middleware koa-middleware semantic-release swagger-documentation swagger-ui webpack3
Last synced: 5 months ago
JSON representation
Adds middleware to your Koa/Express App to serve the Swagger UI bound to your Swagger document. This acts as a living documentation for your APIs hosted from within your App.
- Host: GitHub
- URL: https://github.com/vivek-26/middleware-swagger-ui
- Owner: vivek-26
- License: mit
- Created: 2018-01-23T14:43:14.000Z (over 8 years ago)
- Default Branch: master
- Last Pushed: 2018-02-23T15:46:54.000Z (over 8 years ago)
- Last Synced: 2025-09-07T07:32:20.233Z (10 months ago)
- Topics: commitizen, express-middleware, koa-middleware, semantic-release, swagger-documentation, swagger-ui, webpack3
- Language: TypeScript
- Size: 4.68 MB
- Stars: 0
- Watchers: 1
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- Contributing: CONTRIBUTING.md
- License: LICENSE
- Code of conduct: code-of-conduct.md
Awesome Lists containing this project
README
# Swagger UI as middleware for Koa/Express
[](https://travis-ci.org/vivek-26/middleware-swagger-ui)
[](https://coveralls.io/github/vivek-26/middleware-swagger-ui)
[](https://github.com/prettier/prettier)
[](http://commitizen.github.io/cz-cli/)
[](https://github.com/semantic-release/semantic-release)
### 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`](https://github.com/swagger-api/swagger-ui) version: `3.9.2`
### Usage
**Express** setup:
```js
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()`](https://github.com/swagger-api/swagger-ui/blob/master/docs/usage/oauth2.md)
* **`swaggerOptions: `** Passed to [`swaggerUI()`](https://github.com/swagger-api/swagger-ui/blob/master/docs/usage/configuration.md)
* **`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](http://azimi.me/2015/07/16/split-swagger-into-smaller-files.html). It can resolve `remote` & `local` references (thanks to [whitlockjc](https://github.com/whitlockjc/json-refs)). **`NOTE:`** Using this property overrides **`url`** property.
* **`hideTopbar: `** Hides swagger top bar
**Koa (v2)** setup:
```js
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`](https://github.com/vivek-26/middleware-swagger-ui/tree/master/examples)
### Upcoming
* Add more tests.