@aspirejo/swagger-generator-express

    0.1.0 • Public • Published

    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

    Install

    npm i @aspirejo/swagger-generator-express

    DownloadsWeekly Downloads

    0

    Version

    0.1.0

    License

    MIT

    Unpacked Size

    139 kB

    Total Files

    92

    Last publish

    Collaborators

    • yzakarneh