Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/scttcper/koa2-swagger-ui
Swagger UI as Koa v2 middleware
https://github.com/scttcper/koa2-swagger-ui
koa koa2 swagger swagger-ui
Last synced: about 1 month ago
JSON representation
Swagger UI as Koa v2 middleware
- Host: GitHub
- URL: https://github.com/scttcper/koa2-swagger-ui
- Owner: scttcper
- License: mit
- Fork: true (johnhof/swagger-injector)
- Created: 2016-09-20T20:57:10.000Z (about 8 years ago)
- Default Branch: master
- Last Pushed: 2023-11-06T17:18:08.000Z (12 months ago)
- Last Synced: 2024-09-25T15:58:14.994Z (about 1 month ago)
- Topics: koa, koa2, swagger, swagger-ui
- Language: TypeScript
- Homepage:
- Size: 4.41 MB
- Stars: 102
- Watchers: 5
- Forks: 32
- Open Issues: 8
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
- awesome-humanscape - koa2-swagger-ui - swagger api 문서출력을 위한 middleware (Node.js, koa / Utilites)
README
# koa2-swagger-ui [![NPM version][npm-image]][npm-url] [](https://circleci.com/gh/scttcper/koa2-swagger-ui)
[npm-image]: https://img.shields.io/npm/v/koa2-swagger-ui.svg
[npm-url]: https://npmjs.org/package/koa2-swagger-ui
[travis-img]: https://api.travis-ci.org/scttcper/koa2-swagger-ui.svg?branch=master
[travis-url]: https://travis-ci.org/scttcper/koa2-swagger-ui
[coverage-img]: https://codecov.io/gh/scttcper/koa2-swagger-ui/branch/master/graph/badge.svg
[coverage-url]: https://codecov.io/gh/scttcper/koa2-swagger-ui
> Host swagger ui at a given directory from your koa v2 app
Inspired by:
- [swagger-injector](https://github.com/johnhof/swagger-injector) for serving on a specific route
- [hapi-swaggered-ui](https://github.com/z0mt3c/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](https://github.com/swagger-api/swagger-ui#swaggerui)
defaults:
```javascript
title: 'swagger', // page title
oauthOptions: {}, // passed to initOAuth
swaggerOptions: { // passed to SwaggerUi()
dom_id: 'swagger-ui-container',
url: 'http://petstore.swagger.io/v2/swagger.json', // link to swagger.json
supportedSubmitMethods: ['get', 'post', 'put', 'delete', 'patch'],
docExpansion: 'none',
jsonEditor: false,
defaultModelRendering: 'schema',
showRequestHeaders: false,
swaggerVersion: 'x.x.x' // read from package.json,
validatorUrl: null, // disable swagger-ui validator
},
routePrefix: '/docs', // route where the view is returned
specPrefix: '/docs/spec', // route where the spec is returned
exposeSpec: false, // expose spec file
hideTopbar: false, // hide swagger top bar
favicon: '/favicon.png', // default favicon
customCSS: `h1 { color: red }`, // Add Custom CSS on the html
```
## example
```javascript
import Koa from 'koa';
import { koaSwagger } from 'koa2-swagger-ui';
const app = new Koa();
app.use(
koaSwagger({
routePrefix: '/swagger', // host at /swagger instead of default /docs
swaggerOptions: {
url: 'http://petstore.swagger.io/v2/swagger.json', // example path to json
},
}),
);
app.listen(3000);
```
## example with koa-router and yaml source
depends on yamljs to turn your Yaml into a JS object
```
npm install --save yamljs
```
```javascript
const Koa = require('koa');
const Router = require('koa-router');
const yamljs = require('yamljs');
const koaSwagger = require('koa2-swagger-ui');
const router = new Router({ prefix: '/' });
const app = new Koa();
const router = new Router();
// .load loads file from root.
const spec = yamljs.load('./openapi.yaml');
// example 1 using router.use()
router.use(koaSwagger({ swaggerOptions: { spec } }));
// example 2 using more explicit .get()
router.get('/docs', koaSwagger({ routePrefix: false, swaggerOptions: { spec } }));
app.use(router.routes());
app.listen(3000);
```