# koa-swagger-ui

> Swagger doc generator for koa-joi-router

Latest version **1.1.3** (published 2020-01-09) · MIT license · 0 weekly downloads

## Install

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

## Health

**Score 15/100 (F)** — status: abandoned.

Positive: no vulnerabilities.

Warnings: low downloads; no types; no esm support.

Negative: abandoned; low maintenance score.

## Facts

| | |
|---|---|
| Version | 1.1.3 |
| Published | 2020-01-09 |
| First published | 2017-05-10 |
| Weekly downloads | 0 |
| License | MIT |
| TypeScript types | none |
| Module format | CommonJS |
| Dependencies | 7 |
| Unpacked size | 19.2 KB |
| Known vulnerabilities | 0 (+5 in 3 direct dependencies) |
| Install scripts | no |
| Author | Willin Wang |
| Maintainers | willin |

## Links

- npm: https://www.npmjs.com/package/koa-swagger-ui
- Repository: https://github.com/willin/koa-swagger-ui
- Homepage: https://github.com/willin/koa-swagger-ui#readme
- Issues: https://github.com/willin/koa-swagger-ui/issues
- npm.io page: https://npm.io/package/koa-swagger-ui

## Dependencies (7)

- [joi](https://npm.io/package/joi.md) ^14.3.1
- [lodash](https://npm.io/package/lodash.md) ^4.17.15
- [koa-send](https://npm.io/package/koa-send.md) ^5.0.0
- [joi-to-swagger](https://npm.io/package/joi-to-swagger.md) ^3.3.0
- [path-to-regexp](https://npm.io/package/path-to-regexp.md) ^5.0.0
- [swagger-ui-dist](https://npm.io/package/swagger-ui-dist.md) ^3.24.3
- [joi-to-json-schema](https://npm.io/package/joi-to-json-schema.md) ^5.1.0

## Recent versions

- 1.1.3 (latest) — 2020-01-09
- 1.1.2 — 2019-11-19
- 1.1.1 — 2017-06-21
- 1.1.0 — 2017-06-14
- 1.0.9 — 2017-06-01
- 1.0.8 — 2017-06-01
- 1.0.7 — 2017-05-27
- 1.0.6 — 2017-05-26
- 1.0.5 — 2017-05-25
- 1.0.4 — 2017-05-22
- 1.0.3 — 2017-05-19
- 1.0.2 — 2017-05-19
- 1.0.1 — 2017-05-11
- 1.0.0 — 2017-05-11
- 0.1.0 — 2017-05-10

## README

# koa-swagger-ui

Still missing:
- [x] convert route outputs into swagger
- [ ] finish converting from joi-to-json-schema to [joi-to-swagger](https://github.com/ChiperSoft/joi-to-swagger) (there's no npm link, but there is a github link)
- [ ] make tests to demonstrate
- [ ] find out why swagger-cli throws validate errors on anything I create.



A node module for generating [Swagger 2.0](http://swagger.io/) JSON
definitions from existing [koa-joi-router](https://github.com/koajs/joi-router)
routes.

## Example

```js

const SwaggerAPI = require('joi-router-swagger-docs').SwaggerAPI;
const Router = require('koa-joi-router');
const Joi = Router.Joi;
const router = router();

router.get('/demo',{
   validate: {
      query: {
        name: joi.string().max(100).description('new user name')
      }
    },
    handler: async (ctx) => {
      ctx.status = 200;
      ctx.body = {status: 1, msg: 'hello world'};
    },
    swagger: {
      tags: ['demo'],
      responses: {
        200: {
          description: '查询域名',
          schema: joi.object({
            status: joi.number().integer().default(1),
            server: joi.string().default('js.cool')
          }).label('serverSuccess')
        }
      }
    }
  });

router.get('/signup', {
  validate: {
    type: 'json',
    body: {
      name: Joi.string().max(100).description('new user name')
    },
    output: {
      200: {
        body: {
          userId: Joi.string().description('newly created user id')
        }
      }
    }
  },
  handler: function*() {
    // ...
  }
});

router.get('/about/:versionId', {
  swagger: {
    description: 'Anything in swagger is passed directly onto the swagger object for that path',
    parameters: [
      {name: 'versionId', in: 'path', description: 'this is a good way to get other items onto swagger object.'}
    ]
  },
  handler: function*() {
    // ...
  }
})

//if you use swagger-ui you will want path parameters so people can use the 'try it out' functionality, despite the fact that koa-joi-router doesn't support them
router.get('/user/:id/friends/:friendId', {
  validate: {
    path: Joi.object().keys({
      id: Joi.string().alphanum().max(24).description('id of user').required(),
      friendId: Joi.string().alphanum().max(24).description('id of user\'s friend'),
    })
    output: {
      200: {
        body: {
          userId: Joi.string().description('The friend of the user. they are pretty cool.')
        }
      }
    }
  },
  handler: function*() {
    // ...
  }
});

swaggerAPI = new SwaggerAPI();
swaggerAPI.addJoiRouter(router);

let spec = swaggerAPI.generateSpec({
  info: {
    title: 'Example API',
    description: 'API for creating and editing examples',
    version: '1.1'
  },
  basePath: '/api/v1'
});

console.log(JSON.stringify(spec, null, '  '));
```

## API

### new SwaggerAPI()

Creates a new SwaggerAPI instance.

### swaggerAPI.addJoiRouter(router, options)

Add a joi-router instance to the API. The router should already have all its
routes set up before calling this method (which pulls the route definitions
from the router's `.routes` property).

Options:
- prefix: Prefix to add to Swagger path

### swaggerAPI.generateSpec(baseSpec)

Create a Swagger specification for this API. A base specification should be
provided with an `info` object (containing at least the `title` and `version`
strings) and any other global descriptions.

## Thanks for starting this:

[Pebble Technology!](https://www.pebble.com)

## License

[MIT](https://github.com/paul42/joi-router-swagger-docs/blob/master/LICENSE)

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