Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
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: 14 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 (over 9 years ago)
- Default Branch: master
- Last Pushed: 2024-10-11T05:17:59.000Z (about 1 month ago)
- Last Synced: 2024-10-13T23:41:16.550Z (29 days ago)
- Topics: jsdoc, openapi, swagger, swagger-jsdoc
- Language: JavaScript
- Homepage:
- Size: 3.58 MB
- Stars: 1,690
- Watchers: 11
- Forks: 227
- Open Issues: 43
-
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
- License: LICENSE
Awesome Lists containing this project
- awesome - swagger-jsdoc - Generates swagger doc based on JSDoc. (JavaScript)
- awesome-humanscape - swagger-jsdoc - api 문서를 분리해서 작성하기위한 모듈 (Node.js, koa / Utilites)
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)