# koa2-swagger-ui

> Swagger UI middleware for koa

Latest version **5.12.0** (published 2025-09-16) · MIT license · 0 weekly downloads

## Install

```sh
npm install koa2-swagger-ui
pnpm add koa2-swagger-ui
yarn add koa2-swagger-ui
bun add koa2-swagger-ui
```

## Health

**Score 60/100 (C)** — status: stable.

Positive: has types; no vulnerabilities; has provenance; high quality score.

Warnings: low downloads; no esm support.

## Facts

| | |
|---|---|
| Version | 5.12.0 |
| Published | 2025-09-16 |
| First published | 2016-09-21 |
| Weekly downloads | 0 |
| License | MIT |
| TypeScript types | bundled |
| Module format | CommonJS |
| Dependencies | 3 |
| Unpacked size | 20.8 KB |
| Known vulnerabilities | 0 |
| Install scripts | no |
| Provenance | attested (GitHub Actions) |
| GitHub stars | 111 |
| Maintainers | scttcper |
| Keywords | swagger, docs, swagger-ui, koa, koa2, middleware |

## Links

- npm: https://www.npmjs.com/package/koa2-swagger-ui
- Repository: https://github.com/scttcper/koa2-swagger-ui
- Issues: https://github.com/scttcper/koa2-swagger-ui/issues
- npm.io page: https://npm.io/package/koa2-swagger-ui

## Dependencies (3)

- [lodash](https://npm.io/package/lodash.md) ^4.17.21
- [handlebars](https://npm.io/package/handlebars.md) ^4.7.8
- [read-pkg-up](https://npm.io/package/read-pkg-up.md) 7.0.1

## Alternatives

- [@sindresorhus/slugify](https://npm.io/package/@sindresorhus/slugify.md) — 3.7M weekly downloads
- [solid-js](https://npm.io/package/solid-js.md) — 2.7M weekly downloads
- [expo-glass-effect](https://npm.io/package/expo-glass-effect.md) — 2.5M weekly downloads
- [nanoassert](https://npm.io/package/nanoassert.md) — 780.8K weekly downloads
- [@ffmpeg/ffmpeg](https://npm.io/package/@ffmpeg/ffmpeg.md) — 529.5K weekly downloads

## Recent versions

- 5.12.0 (latest) — 2025-09-16
- 5.11.0 — 2024-11-18
- 5.10.0 — 2023-11-06
- 5.9.1 — 2023-10-02
- 5.9.0 — 2023-08-23
- 5.8.0 — 2023-05-15
- 5.7.0 — 2023-01-18
- 5.6.0 — 2022-06-20
- 5.5.1 — 2022-05-12
- 5.5.0 — 2022-03-14
- 5.4.0 — 2022-03-06
- 5.3.0 — 2021-11-13
- 5.2.1 — 2021-10-02
- 5.2.0 — 2021-06-25
- 5.1.0 — 2021-04-05
- … 106 more at https://npm.io/package/koa2-swagger-ui/versions

## README

# koa2-swagger-ui [![NPM version][npm-image]][npm-url]

[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);
```

---
_Source: https://npm.io/package/koa2-swagger-ui · Machine-readable twin of the npm.io package page. Health data is recomputed on every publish._