gatsby-plugin-swagger-jsdoc/README.md

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

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