# swagger-express-jsdoc

> Generates swagger JSDoc with express

Latest version **1.0.4** (published 2019-05-23) · MIT license · 0 weekly downloads

## Install

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

## 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.0.4 |
| Published | 2019-05-23 |
| First published | 2017-04-20 |
| Weekly downloads | 0 |
| License | MIT |
| TypeScript types | none |
| Module format | CommonJS |
| Dependencies | 8 |
| Unpacked size | 11.4 KB |
| Known vulnerabilities | 0 (+2 in 1 direct dependencies) |
| Install scripts | no |
| GitHub stars | 12 |
| Maintainers | sanghaklee |
| Keywords | jsdoc, api, express, swagger |

## Links

- npm: https://www.npmjs.com/package/swagger-express-jsdoc
- Repository: https://github.com/SangHakLee/swagger-express-jsdoc
- Homepage: https://github.com/SangHakLee/swagger-express-jsdoc#readme
- Issues: https://github.com/SangHakLee/swagger-express-jsdoc/issues
- npm.io page: https://npm.io/package/swagger-express-jsdoc

## Dependencies (8)

- [ejs](https://npm.io/package/ejs.md) ^2.6.1
- [morgan](https://npm.io/package/morgan.md) ^1.9.1
- [express](https://npm.io/package/express.md) ^4.17.0
- [body-parser](https://npm.io/package/body-parser.md) ^1.19.0
- [cookie-parser](https://npm.io/package/cookie-parser.md) ^1.4.4
- [serve-favicon](https://npm.io/package/serve-favicon.md) ^2.5.0
- [swagger-jsdoc](https://npm.io/package/swagger-jsdoc.md) ^3.2.9
- [swagger-ui-express](https://npm.io/package/swagger-ui-express.md) ^4.0.4

## Recent versions

- 1.0.4 (latest) — 2019-05-23
- 1.0.3 — 2017-04-20
- 1.0.2 — 2017-04-20
- 1.0.1 — 2017-04-20

## README

# swagger-express-jsdoc
Example of [Express][1] with [swagger-jsdoc][2]

[![NPM](https://nodei.co/npm/swagger-express-jsdoc.png?downloads=true&downloadRank=true&stars=true)](https://nodei.co/npm/swagger-express-jsdoc/)

## Install
### git
```bash
$ git clone https://github.com/SangHakLee/swagger-express-jsdoc.git
```

### NPM
```bash
$ npm i swagger-express-jsdoc
$ cd node_modules
```

## How to use
### Start Server
```bash
$ cd swagger-express-jsdoc
$ npm install
$ npm start
```
### Use swagger-jsdoc
http://localhost:3000/api-docs/

## How to add api-docs
This application is based on [Swagger][3], [swagger-jsdoc][4] and [swagger-ui-express][5]
### app.js
```javascript
// ...
var swaggerUi = require('swagger-ui-express'); // line 7
var swaggerJSDoc = require('swagger-jsdoc'); // line 8

// ...
var options = { // line 27
  swaggerDefinition: {
    info: {
      title: 'swagger-express-jsdoc', // Title (required)
      version: '1.0.0', // Version (required)
    },
  },
  apis: ['./routes/*'], // Path to the API docs
};
var swaggerSpec = swaggerJSDoc(options); // line 36

// ...
app.get('/api-docs.json', function(req, res) { // line 41
  res.setHeader('Content-Type', 'application/json');
  res.send(swaggerSpec);
});

// ...
app.use('/api-docs', swaggerUi.serve, swaggerUi.setup(swaggerSpec)); // line 45
```
#### var options (line 27)
 Your Swagger docs information here.
[swagger-jsdoc][6]

##### swaggerDefinition.info
[specification][7]

```json
{
  "title": "Swagger Sample App",
  "description": "This is a sample server Petstore server.",
  "termsOfService": "http://swagger.io/terms/",
  "contact": {
    "name": "API Support",
    "url": "http://www.swagger.io/support",
    "email": "support@swagger.io"
  },
  "license": {
    "name": "Apache 2.0",
    "url": "http://www.apache.org/licenses/LICENSE-2.0.html"
  },
  "version": "1.0.1"
}
```
##### apis
Your routing files path.
If your routing file path like this, 
- /controllers/users.js
- /controllers/stores.js

Set your `apis` value like this, **apis: ['./controllers/*']**

#### var swaggerSpec (line 36)
It will be json object.
Your `option` value and `apis` value are combined.

#### /api-docs.json (line 41)
This returns a simple json document.
http://localhost:3000/api-docs.json

#### /api-docs (line 45)
This will convert the json document to Swagger-ui.
So when you connect with http://localhost:3000/api-docs, it will make you see beautiful documents.

  [1]: http://expressjs.com/
  [2]: https://github.com/Surnet/swagger-jsdoc
  [3]: http://swagger.io/
  [4]: https://github.com/Surnet/swagger-jsdoc
  [5]: https://github.com/scottie1984/swagger-ui-express
  [6]: https://github.com/Surnet/swagger-jsdoc
  [7]: http://swagger.io/specification/

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