# express-swagger-generator

> Generates swagger doc & ui based on express existing routes.

Latest version **1.1.17** (published 2020-01-08) · MIT license · 0 weekly downloads

> **Deprecated.** This package is deprecated.

## Install

```sh
npm install express-swagger-generator
pnpm add express-swagger-generator
yarn add express-swagger-generator
bun add express-swagger-generator
```

## Health

**Score 10/100 (F)** — status: deprecated.

Negative: deprecated.

## Facts

| | |
|---|---|
| Version | 1.1.17 |
| Published | 2020-01-08 |
| First published | 2017-03-27 |
| Weekly downloads | 0 |
| License | MIT |
| TypeScript types | none |
| Module format | CommonJS |
| Dependencies | 6 |
| Unpacked size | 29 KB |
| Known vulnerabilities | 0 |
| Install scripts | no |
| Author | https://github.com/pgroot/express-swagger-generator/graphs/contributors |
| Maintainers | groot |
| Keywords | express, swagger, api, swagger-ui, restful |

## Links

- npm: https://www.npmjs.com/package/express-swagger-generator
- Repository: https://github.com/pgroot/express-swagger-generator
- Issues: https://github.com/pgroot/express-swagger-generator/issues
- npm.io page: https://npm.io/package/express-swagger-generator

## Dependencies (6)

- [glob](https://npm.io/package/glob.md) ^7.0.3
- [doctrine](https://npm.io/package/doctrine.md) ^2.0.0
- [doctrine-file](https://npm.io/package/doctrine-file.md) ^1.0.2
- [swagger-parser](https://npm.io/package/swagger-parser.md) ^5.0.5
- [recursive-iterator](https://npm.io/package/recursive-iterator.md) ^2.0.3
- [express-swaggerize-ui](https://npm.io/package/express-swaggerize-ui.md) ^1.0.3

## Recent versions

- 1.1.17 (latest) — 2020-01-08
- 1.1.16 — 2020-01-08
- 1.1.15 — 2019-06-21
- 1.1.14 — 2019-04-09
- 1.1.13 — 2019-02-18
- 1.1.12 — 2019-02-18
- 1.1.11 — 2018-12-10
- 1.1.10 — 2018-11-01
- 1.1.9 — 2018-08-28
- 1.1.8 — 2018-08-28
- 1.1.7 — 2018-07-30
- 1.1.6 — 2018-07-25
- 1.1.5 — 2018-07-23
- 1.1.4 — 2018-06-01
- 1.1.3 — 2018-06-01
- … 8 more at https://npm.io/package/express-swagger-generator/versions

## README

### Express Swagger Generator

#### Installation

```
npm i express-swagger-generator --save-dev
```

#### Usage

```
const express = require('express');
const app = express();
const expressSwagger = require('express-swagger-generator')(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
};
expressSwagger(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-swaggerize-ui](https://github.com/pgroot/express-swaggerize-ui) and [Doctrine-File](https://github.com/researchgate/doctrine-file)

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