# gatsby-plugin-swagger-jsdoc

> A Gatsby plugin to automatically generate Swagger OpenAPI spec from JSDoc-style comments

Latest version **1.0.1** (published 2022-07-10) · MIT license · 0 weekly downloads

## Install

```sh
npm install gatsby-plugin-swagger-jsdoc
pnpm add gatsby-plugin-swagger-jsdoc
yarn add gatsby-plugin-swagger-jsdoc
bun add gatsby-plugin-swagger-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.1 |
| Published | 2022-07-10 |
| First published | 2022-07-05 |
| Weekly downloads | 0 |
| License | MIT |
| TypeScript types | none |
| Module format | CommonJS |
| Node | >=14.15.0 |
| Dependencies | 3 |
| Unpacked size | 7.1 KB |
| Known vulnerabilities | 0 |
| Install scripts | no |
| GitHub stars | 1 |
| Author | Yumin Chen |
| Maintainers | chen.so |
| Keywords | gatsby, gatsby-plugin, swagger, swagger-jsdoc, swagger-ui |

## Links

- npm: https://www.npmjs.com/package/gatsby-plugin-swagger-jsdoc
- Repository: https://github.com/yumin-chen/gatsby-plugin-swagger-jsdoc
- Homepage: https://github.com/yumin-chen/gatsby-plugin-swagger-jsdoc#readme
- Issues: https://github.com/yumin-chen/gatsby-plugin-swagger-jsdoc/issues
- npm.io page: https://npm.io/package/gatsby-plugin-swagger-jsdoc

## Dependencies (3)

- [swagger-jsdoc](https://npm.io/package/swagger-jsdoc.md) latest
- [@babel/runtime](https://npm.io/package/@babel/runtime.md) latest
- [swagger-ui-react](https://npm.io/package/swagger-ui-react.md) latest

## Recent versions

- 1.0.1 (latest) — 2022-07-10
- 1.0.0 — 2022-07-10
- 0.1.1 — 2022-07-06
- 0.1.0 — 2022-07-05
- 0.0.6 — 2022-07-05
- 0.0.5 — 2022-07-05
- 0.0.4 — 2022-07-05
- 0.0.3 — 2022-07-05
- 0.0.2 — 2022-07-05
- 0.0.1 — 2022-07-05

## 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;
```

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