https://github.com/surnet/swagger-jsdoc
Generates swagger/openapi specification based on jsDoc comments and YAML files.
https://github.com/surnet/swagger-jsdoc
jsdoc openapi swagger swagger-jsdoc
Last synced: 19 days ago
JSON representation
Generates swagger/openapi specification based on jsDoc comments and YAML files.
- Host: GitHub
- URL: https://github.com/surnet/swagger-jsdoc
- Owner: Surnet
- License: mit
- Created: 2015-06-06T08:36:18.000Z (almost 10 years ago)
- Default Branch: master
- Last Pushed: 2025-04-16T15:27:09.000Z (26 days ago)
- Last Synced: 2025-04-18T15:16:54.927Z (24 days ago)
- Topics: jsdoc, openapi, swagger, swagger-jsdoc
- Language: JavaScript
- Homepage:
- Size: 3.07 MB
- Stars: 1,731
- Watchers: 10
- Forks: 229
- Open Issues: 40
-
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
- License: LICENSE
Awesome Lists containing this project
README
# swagger-jsdoc
This library reads your [JSDoc](https://jsdoc.app/)-annotated source code and generates an [OpenAPI (Swagger) specification](https://swagger.io/specification/).
[](https://www.npmjs.com/package/swagger-jsdoc)
## Getting started
Imagine having API files like these:
```javascript
/**
* @openapi
* /:
* get:
* description: Welcome to swagger-jsdoc!
* responses:
* 200:
* description: Returns a mysterious string.
*/
app.get('/', (req, res) => {
res.send('Hello World!');
});
```
The library will take the contents of `@openapi` (or `@swagger`) with the following configuration:
```javascript
const swaggerJsdoc = require('swagger-jsdoc');
const options = {
definition: {
openapi: '3.0.0',
info: {
title: 'Hello World',
version: '1.0.0',
},
},
apis: ['./src/routes*.js'], // files containing annotations as above
};
const openapiSpecification = swaggerJsdoc(options);
```
The resulting `openapiSpecification` will be a [swagger tools](https://swagger.io/tools/)-compatible (and validated) specification.
## System requirements
- Node.js 12.x or higher
You are viewing `swagger-jsdoc` v6 which is published in CommonJS module system.
## Installation
```bash
npm install swagger-jsdoc --save
```
Or
```bash
yarn add swagger-jsdoc
```
## Supported specifications
- OpenAPI 3.x
- Swagger 2
- AsyncAPI 2.0
## Validation of swagger docs
By default `swagger-jsdoc` tries to parse all docs to it's best capabilities. If you'd like to you can instruct an Error to be thrown instead if validation failed by setting the options flag `failOnErrors` to `true`. This is for instance useful if you want to verify that your swagger docs validate using a unit test.
```javascript
const swaggerJsdoc = require('swagger-jsdoc');
const options = {
failOnErrors: true, // Whether or not to throw when parsing errors. Defaults to false.
definition: {
openapi: '3.0.0',
info: {
title: 'Hello World',
version: '1.0.0',
},
},
apis: ['./src/routes*.js'],
};
const openapiSpecification = swaggerJsdoc(options);
```
## Documentation
Click on the version you are using for further details:
- [7.x](https://github.com/Surnet/swagger-jsdoc/tree/v7/docs)
- [6.x](https://github.com/Surnet/swagger-jsdoc/tree/v6/docs)
- [5.x](https://github.com/Surnet/swagger-jsdoc/tree/v5)