JSdoc to Swagger document generator

A while back I wrote an NPM module that is able to take your endpoint actions annotated with some JSdoc documentation and turn it into a Swagger JSON document that can be used to import into Postman, Insomnia, or generate a Redoc document for storage in the repository. 

The purpose of this module is to generate Swagger documentation from the JSDoc tags you have annotated your endpoint handlers with. It is able to interpret complex types as well.

Something like the following can be translated into a nice Swagger document:

 

									/**
									 * @typedef ResponseModel
									 *
									 * @property {boolean} - likely to be false in an error response
									 * @property {string} message - the message describing the success state
									 */
									
									/**
									 * @typedef {ResponseModel} ExpectedModel 
									 * @property {SomeModel[]} - a list of items we've found.
									 */
									
									/**
									 * @swagger
									 *
									 * Just put the complete description here. It is the description that is shown when you click into a 
									 * swagger endpoint in the interface.
									 *
									 * @summary This is the short text shown right next to the endpoint name
									 * @tag TestEndpoint
									 *
									 * @param req       the request object
									 * @param resp      the reponse object
									 *
									 * @param pathParameter {number} (path) part of the url
									 * @param queryParam {string} (query) part of the requestquery (?queryParam=blaat)
									 * @param headerParam {string} (header) expected header value from request headers
									 * @param bodyModel  {ExpectedModel} (body) This is a complex type parameter that has a proper type hint.
									 *
									 * @response 403    You cannot go here.
									 * @response 200    {ExpectedModel} all is well, information is returned in complex type.
									 */
									module.exports = function(req, resp) {
									
									 // your code here.
									
									};

 

Interested? Have a look here to start using it in your project.

Also Read

Bloomreach XIN mods

By Marnix Kok on 22 November 2021

LINCS: a linear constraint solver

By The Digital Team on 26 September 2021

Kinect SDK: surrounded by bees

By The Digital Team on 26 September 2021