jsdoc-openapi

JSDoc Comments for the OpenApi Specification

A fork of swagger-jsdoc that brings a cleaner way to document your code for generating OpenAPI (Swagger) specs.

Installation

$ yarn add jsdoc-openapi

Usage

const jsdocParser = require("jsdoc-openapi");
 
// normal OpenAPI definition
const openAPIDefinition = {
  openapi: "3.0.0",
  info: {
    title: "Title of your service",
    version: "1.0.0",
  }
}
 
const spec = jsdocParser({
  swaggerDefinition: openAPIDefinition,
  apis: ["src/**/*.js"] // paths to files with comments to be parsed
});

Swagger UI Express example

const jsdocParser = require("jsdoc-openapi");
const swaggerUi = require("swagger-ui-express");
 
const spec = jsdocParser({
  swaggerDefinition: openAPIDefinition,
  apis: ["src/routes/my-route.js"]
});
 
app.use("/api-docs", swaggerUi.serve, swaggerUi.setup(spec));

Comment syntax

/**
 * <METHOD> /<path>
 * @<property> {<type>} <name> - <description>
 */

Available properties (so far):

• @description
• @operationId
• @summary
• @deprecated
• @pathParam
• @queryParam
• @requestBody
• @requestBodyForm
• @response

types:

• integer
• number
• string
• boolean
• object
• optional: [<type>]
• array: <type>[]

Basic comment example

/**
 * GET /hello
 * @description Get a "hello world" message.
 * @response {string} 200 - hello world.
 */

OpenAPI equivalent:

/hello:
  get:
    description: Get a "hello world" message.
    responses:
      200:
        description: hello world.
        schema:
          type: string

Advanced comment example

/**
 * GET /api/v1/cars/{country}/{city} 
 * @description Get a list of cars at a location.
 * @pathParam {string} country - Country of the rental company.
 * @pathParam {string} city - City of the rental company.
 * @queryParam {[string]} company - Rental Company name.
 * @queryParam {[string]} car - Car Name.
 * @queryParam {[string]} type - Car Type.
 * @queryParam {[string]} style - Car Style.
 * @queryParam {[number]} mincost - Min Cost.
 * @queryParam {[number]} maxcost - Max Cost.
 * @response {Car[]} 200 - A list of cars.
 * @response 400 - Example Error.
 */

definitions:
  Car:
    type: object
    properties:
      id:
        type: string
      city:
        type: string
      country:
        type: string
      name:
        type: string
      company:
        type: string
      image:
        type: string
      cost:
        type: number
      type:
        type: string
      style:
        type: string

OpenAPI equivalent:

 /api/v1/cars/{country}/{city}:
   get:
     description: Get a list of cars at a location.
     parameters:
       - in: path
         name: country
         description: Country of the rental company
         required: true
         schema:
           type: string
       - in: path
         name: city
         description: City ofthe rental company
         required: true
         schema:
           type: string
       - in: query
         name: company
         description: Renatal Company name
         schema:
           type: string
       - in: query
         name: car
         description: Car Name
         schema:
           type: string
       - in: query
         name: type
         description: Car Type
         schema:
           type: string
       - in: query
         name: style
         description: Car Style
         schema:
           type: string
       - in: query
         name: mincost
         description: Min Cost
         schema:
           type: string
       - in: query
         name: maxcost
         description: Max Cost
         schema:
           type: string
     responses:
       200:
         description: Success
         schema:
          type: array
          items:
            type: object
            properties:
              id:
                type: string
              city:
                type: string
              country:
                type: string
              name:
                type: string
              company:
                type: string
              image:
                type: string
              cost:
                type: number
              type:
                type: string
              style:
                type: string
       400:
         description: Example Error