Community Plugin

gatsby-plugin-swagger-jsdoc

Provides drop-in support for generating a Swagger UI docs page for your REST API backend, automatically generated from JSDoc-style comments.

This plugin uses swagger-jsdoc to generate the OpenAPI Specification definition required by Swagger UI, and then renders the result using the official swagger-ui-react package.

Install

npm install gatsby-plugin-swagger-jsdoc

How to use

Add in your gatsby-config.js:

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 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:

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:

// 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;