# koa-swagger-generator-api

> A fork of express-swagger-generator compatible to work with KOA.

Latest version **1.1.0** (published 2020-04-13) · MIT license · 0 weekly downloads

## Install

```sh
npm install koa-swagger-generator-api
pnpm add koa-swagger-generator-api
yarn add koa-swagger-generator-api
bun add koa-swagger-generator-api
```

## 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.0 |
| Published | 2020-04-13 |
| First published | 2020-04-13 |
| Weekly downloads | 0 |
| License | MIT |
| TypeScript types | none |
| Module format | CommonJS |
| Dependencies | 9 |
| Unpacked size | 28 KB |
| Known vulnerabilities | 0 |
| Install scripts | no |
| GitHub stars | 1 |
| Author | Yadickson Soto |
| Maintainers | yadickson |
| Keywords | koa, swagger, middleware, ui, annotation, documentation |

## Links

- npm: https://www.npmjs.com/package/koa-swagger-generator-api
- Repository: https://github.com/yadickson/koa-swagger-generator-api
- Issues: https://github.com/yadickson/koa-swagger-generator-api/issues
- npm.io page: https://npm.io/package/koa-swagger-generator-api

## Dependencies (9)

- [koa](https://npm.io/package/koa.md) ^2.10.0
- [glob](https://npm.io/package/glob.md) ^7.1.6
- [koa-mount](https://npm.io/package/koa-mount.md) ^4.0.0
- [koa-router](https://npm.io/package/koa-router.md) ^8.0.6
- [koa-static](https://npm.io/package/koa-static.md) ^5.0.0
- [doctrine-file](https://npm.io/package/doctrine-file.md) ^2.0.1
- [swagger-parser](https://npm.io/package/swagger-parser.md) ^8.0.4
- [koa-swaggerize-ui](https://npm.io/package/koa-swaggerize-ui.md) ^1.1.0
- [recursive-iterator](https://npm.io/package/recursive-iterator.md) ^3.3.0

## 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

- 1.1.0 (latest) — 2020-04-13
- 1.0.0 — 2020-04-13

## README

### Koa Swagger Generator (forked from Express-swagger-generator)

[![TravisCI Status][travis-image]][travis-url]
[![npm version][npm-image]][npm-url]

#### Installation

```
npm i koa-swagger-generator-api --save-dev
```

#### Usage

```
const Koa = require('koa');
const app = new Koa();

const koaSwagger = require('koa-swagger-generator-api')(app);

let options = {
    swaggerDefinition: {
        info: {
            description: 'This is a sample server',
            title: 'Swagger',
            version: '1.0.0',
        },
        host: 'localhost:3000',
        basePath: '/v1',
        produces: [
            "application/json",
            "application/xml"
        ],
        schemes: ['http', 'https'],
		securityDefinitions: {
            JWT: {
                type: 'apiKey',
                in: 'header',
                name: 'Authorization',
                description: "",
            }
        }
    },
    basedir: __dirname, //app absolute path
    files: ['./routes/**/*.js'] //Path to the API handle folder
};
koaSwagger(options)
app.listen(3000);
```

Open [http://<app_host>:<app_port>/api-docs]() in your browser to view the documentation.

#### How to document the API

```
/**
 * This function comment is parsed by doctrine
 * @route GET /api
 * @group foo - Operations about user
 * @param {string} email.query.required - username or email - eg: user@domain
 * @param {string} password.query.required - user's password.
 * @returns {object} 200 - An array of user info
 * @returns {Error}  default - Unexpected error
 */
exports.foo = function() {}
```

For model definitions:

```
/**
 * @typedef Product
 * @property {integer} id
 * @property {string} name.required - Some description for product
 * @property {Array.<Point>} Point
 */

/**
 * @typedef Point
 * @property {integer} x.required
 * @property {integer} y.required - Some description for point - eg: 1234
 * @property {string} color
 * @property {enum} status - Status values that need to be considered for filter - eg: available,pending
 */

/**
 * @typedef Error
 * @property {string} code.required
 */

/**
 * @typedef Response
 * @property {[integer]} code
 */


/**
 * This function comment is parsed by doctrine
 * sdfkjsldfkj
 * @route POST /users
 * @param {Point.model} point.body.required - the new point
 * @group foo - Operations about user
 * @param {string} email.query.required - username or email
 * @param {string} password.query.required - user's password.
 * @param {enum} status.query.required - Status values that need to be considered for filter - eg: available,pending
 * @operationId retrieveFooInfo
 * @produces application/json application/xml
 * @consumes application/json application/xml
 * @returns {Response.model} 200 - An array of user info
 * @returns {Product.model}  default - Unexpected error
 * @returns {Array.<Point>} Point - Some description for point
 * @headers {integer} 200.X-Rate-Limit - calls per hour allowed by the user
 * @headers {string} 200.X-Expires-After - 	date in UTC when token expires
 * @security JWT
 */
```

#### More

This module is based on [express-swagger-generator](https://github.com/pgroot/express-swagger-generator),  [express-swaggerize-ui](https://github.com/pgroot/express-swaggerize-ui) and [Doctrine-File](https://github.com/researchgate/doctrine-file)

## License

MIT © [Yadickson Soto](https://github.com/yadickson)

Thanks to [koa-swagger-generator](https://github.com/arizorin/koa-swagger-generator)

[travis-image]: https://travis-ci.org/yadickson/koa-swagger-generator-api.svg?branch=master
[travis-url]: https://travis-ci.org/yadickson/koa-swagger-generator-api

[npm-image]: https://badge.fury.io/js/koa-swagger-generator-api.svg
[npm-url]: https://badge.fury.io/js/koa-swagger-generator-api

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