swaggerise v1.0.9
swaggerise
A command-line utility to generate Swagger compatible yaml and json by parsing Router annotations.
Installation
NA
Notes
- It can only be run on the root folder of a express-style project. ( It must have a route folder where all router files are present)
- The project root folder can contain a schema folder which will be scanned for external object schema. ( Useful for representing objects which are sent in the body of a request. Currently only JOI schema is supported)
- A conf file will be generated if not present in the project folder. Users must take care to edit the conf file before generating the swagger yaml.
- All route files must export only the router object. Else, it won't be considered as a route file.
Usage
Run the index file on a express project root folder.
express-project-root> node ./path-to-swaggerise/index.js
Router annotations : 1. @parameters - Reference to external schema file. Syntax is '#/path-to-schema-file'. If more than one schema is exported from the schema file, access it like a regular JSON. Ex. '#/path-to-schema-file.propertyKey'. 2. @description - Description for this particular endpoint. 3. @summary - Summary for the particular endpoint. 4. @operationId - Unique operation id 5. @produces - Stringified JSON array of response type. 6. @consumes - Stringified JSON array of api input type. 7. @responses - Stringified JSON object of possible response codes and description for them.
Module annotations : 1. @@description - Description for the whole router file/module. 2. @externalDocDesc - Description for external document for the module. 3. @externalDocUrl - Url for the external document.
Example
Router annotation :
/**
* @parameters #/user.js.add
* @description Description for this path
* @summary Summary for this route
* @operationId Unique operation id
* @produces ["application/json"]
* @consumes ["application/json"]
* @responses '{"200":{"description":"successful operation"}}'
*/
server.post('/add', validation(schema.add), async (req, res, next) => {
//Endpoint handler.
}
Module annotation :
/**
* @description hello
* @externalDocDesc doc
* @externalDocUrl http://tis.io/terms/
*/
module.exports = router;
TO-DO
- Add support for other external schema types other than Joi.