@aspirejo/swagger-generator-express

swagger-generator-express

Reads the JsDoc comments and generates OpenAPI -Swagger- friendly documentation for NodeJs express application.

for more info visit jsdoc & OpenAPI

Prerequisites

There are three expected types that the generator depends on; Controller, Schema and Model, controllers are the handlers of the request, schemas are the request input structure (and validators), and models are the response object(s). All types are loaded dynamically into the generator based on a configurable pattern.

A controller file name must have a pattern that can be used to identify both method (http) and version from it.

for more info about schema validations see express-validator

Install

npm install @aspirejo/swagger-denerator-express

Usage

import generator from '@aspirejo/swagger-denerator-express';
generator.generate(config);

const generator = require('@aspirejo/swagger-denerator-express');
generator.generate(config);

Configuration

- specs
    |- swagger
    |- host
    |- basePath
    |- schemes
    |- consumes
    |- produces
- baseRoute
- patterns
    |- models
    |- schemas
    |- controllers
    |- controllerInfoResolver
- output
    |- location
    |- format
- tags
- params
- versions
- customResponses

specs

required

An object contains the description of the OpenAPI specifications for the APIs

key	type	default value
swagger	string	2.0
host	string
basePath	string	/api/
schemes	string[]	[http, https]
consumes	string[]	[application/json]
produces	string[]	[application/json]

baseRoute

required

A string contains the base route format. MUST contain {version} and {route} placeholders

patterns

required

An object contains the globbing pattern for models, schemas and controllers, it also specifies the controller name regex that will be used to extract method and version.

key	type	default value
models	string
schemas	string
controllers	string
controllerInfoResolver	function

controllerInfoResolver

A function to resolve controller name into a method and a version.

Expected returned object

{
  method
  version
}

output

required

An object that defines output settings

key	type	default value
location	string
format	string

Supported formats are limited to json and yaml only

tags

optional

A list of structured objects that represents all the documentation tags

Expected tag object

{
  name
  description
}

params

optional

A structured object that contains the common parameters definitions.

Keep in mind that if an endpoint contains a path parameter that is not defined in the doucmentation the swagger (OpenAPI) parser will show an error.

versions

optional

A structured object that contains the definition of the parameters that will be applied on all endpoints for that version. Object should be structured as follow:

{
  VERSION_NAME:[
    ARRAY_OF_PARAMETERS_DEFINITIONS
  ]
}

customResponses

optional

A structured object that contains the reponse result for codes that is not generated by default

Default response codes

• 200 : success
• 400 : bad request
• 500 : error

Configurations example

{
  baseRoute: '/{version}/{route}',
  specs: {
    host: "aspire.jo",
  },
  patterns: {
    controllerInfoResolver: async fileName => {
      const [, method, version] = /(delete|get|post|put|patch)\.(v\d+)(\.\S+)*\.js$/.exec(fileName);
      return { method, version };
    },
    models: `${path.resolve(__dirname, './app/')}/**/models/**/*.js`,
    schemas: `${path.resolve(__dirname, './app/')}/**/schema/**/*.js`,
    controllers: `${path.resolve(__dirname, './app/')}/**/controllers/**/_*.js`,
  },
  tags: [
    { name: 'User', description: 'User management endpoints' },
    { name: 'Cart', description: 'Cart endpoints' }
  ],
  output: {
    location: path.join(__dirname, './documentation/output'),
    format: 'json'
  },
  params: {
    id: {
      name: 'id',
      in: 'path',
      description: 'Targeted object ID',
      required: true,
      type: 'number',
    },
  },
  versions: {
    v1: [
      {
        name: 'Authorization',
        in: 'header',
        description: 'Authorization token',
        required: true,
        type: 'string',
      },
    ],
  },
  customResponses: {
    204: {
      description: 'No content',
      schema: {
        properties: {
          code: {
            type: 'number',
          },
          message: {
            type: 'string',
          },
        },
      },
    },
    403: {
      description: 'Unauthorized',
      schema: {
        properties: {
          code: {
            type: 'number',
          },
          message: {
            type: 'string',
          },
        },
      },
    }
  }
}

Adding documentation to code

See generator

Adding new endpoint

See new-endpoint