https://github.com/yumin-chen/gatsby-plugin-swagger-jsdoc
A Gatsby plugin to automatically generate Swagger OpenAPI spec from JSDoc-style comments
https://github.com/yumin-chen/gatsby-plugin-swagger-jsdoc
Last synced: 5 days ago
JSON representation
A Gatsby plugin to automatically generate Swagger OpenAPI spec from JSDoc-style comments
- Host: GitHub
- URL: https://github.com/yumin-chen/gatsby-plugin-swagger-jsdoc
- Owner: yumin-chen
- Created: 2022-07-05T13:49:52.000Z (almost 4 years ago)
- Default Branch: main
- Last Pushed: 2022-07-10T19:56:18.000Z (almost 4 years ago)
- Last Synced: 2025-11-19T11:03:18.372Z (7 months ago)
- Language: JavaScript
- Size: 61.5 KB
- Stars: 1
- Watchers: 1
- Forks: 0
- Open Issues: 1
-
Metadata Files:
- Readme: README.md
Awesome Lists containing this project
README
# gatsby-plugin-swagger-jsdoc
Provides drop-in support for generating a [Swagger UI](https://swagger.io/tools/swagger-ui/) docs page for your REST API backend, automatically generated from JSDoc-style comments.
This plugin uses [swagger-jsdoc](https://github.com/Surnet/swagger-jsdoc) to generate the [OpenAPI Specification](https://swagger.io/specification/) definition required by Swagger UI, and then renders the result using the official [swagger-ui-react](https://www.npmjs.com/package/swagger-ui-react) package.
## Install
`npm install gatsby-plugin-swagger-jsdoc`
## How to use
Add in your `gatsby-config.js`:
```javascript
plugins: [
{
resolve: 'gatsby-plugin-swagger-jsdoc',
options: {
uiRoute: '/api', // Path to your desired API docs page
source: [`${__dirname}/src/api/**/*.js`], // Recursively scan `api` folder
definition: {
info: {
title: 'Your API Title',
description: 'Your API description',
version: '1.0.0',
},
},
},
},
];
```
Now you can add your JSDoc-style comments to your source code, and your API docs page will be built automatically. You could follow the sample JSDoc in [examples](#examples) below.
## Configuration options
**`uiRoute`** [array|string][required]
The path to your desired API docs page, where the generated Swagger UI is shown. This page will be auto-generated by this plugin.
**`source`** [array|string][optional]
Paths of the source files to scan for `@openapi` annotations. By default, it scans the `api` folder and all its subfolders (`['/src/api/**/*.js']`). You can change the value to scan any files, but only JSDoc-style comments are scanned. `**/*` means recursively scan subfolders.
**`definition`** [object][optional]
Extra properties to pass down to Swagger spec definition. For example, you could put your API info definition here:
```javascript
definition: {
info: {
title: 'Your API Title',
description: 'Your API description',
version: '1.0.0'
}
}
```
## Examples
Add `@openapi` annotated JSDoc-style comments to any source file you wish, as long as your source file is listed under the `source` option:
```javascript
// src/api/letters/[value].js
const handler = async (req, res) => {
switch (req.method) {
case 'GET':
/**
* @openapi
* /api/letters/{value}:
* get:
* summary: Get details of a letter by value.
* description: Returns the details information about a letter.
* tags:
* - Letters
* parameters:
* - name: value
* in: path
* description: Value of the letter
* schema:
* type: string
* responses:
* 200:
* description: Success
* content:
* application/json:
* schema:
* type: object
* properties:
* value:
* type: string
* name:
* type: string
* greekAlt:
* type: string
*/
// You could generate a static .json result by plugin `gatsby-plugin-copy-files`,
// or using GraphQL query by plugin `gatsby-plugin-json-output`.
return res.sendFile(`api/letters/${req.params.value}.json`);
case 'POST':
/**
* @openapi
* /api/letters:
* post:
* summary: Add a letter.
* description: This API will make changes and push changes to git remote
* tags:
* - Letters
* responses:
* 200:
* description: OK
*/
// ... YOUR POST METHOD
default:
return res.sendStatus(405);
}
};
export default handler;
```