You can not select more than 25 topics
Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.
81 lines
1.8 KiB
81 lines
1.8 KiB
3 years ago
|
# 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
|
||
|
|
|
||
|
|
## 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)
|