Package Exports

gatsby-plugin-swagger-jsdoc
gatsby-plugin-swagger-jsdoc/index.js

This package does not declare an exports field, so the exports above have been automatically detected and optimized by JSPM instead. If any package subpath is missing, it is recommended to post an issue to the original package (gatsby-plugin-swagger-jsdoc) to support the "exports" field. If that is not possible, create a JSPM override to customize the exports field for this package.

Readme

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;