@aspirejo/swagger-generator-express
v0.1.0
Published
Swagger document generator for NodeJs express application
Downloads
14
Maintainers
Readme
swagger-generator-express
Reads the JsDoc
comments and generates OpenAPI
-Swagger
- friendly documentation for NodeJs express application.
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
andyaml
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