Command line script that generates a swagger file based on jsdoc comments.
You can use the command as follows
config.js is the path to the configuration file.
If you don't specify a configuration file the command will look by default
swaggerJsdoc.config.js in the current working directory.
This will print in the standard output a swagger definition in JSON format, so you can easily pipe the output to another command or to a file.
swagger-jsdoc-generator config.js | mySwaggerDoc.json
or, assuming you have some utility to convert the definition to HTML, you could do
swaggerToHtml < swagger-jsdoc-generator config.js
More detailed example on how to configure and use the command later here.
This package requires Node.js (version >= 4.0.0) and NPM (version >= 2.14.2).
npm install --global swagger-jsdoc-generator
As dev dependency (e.g. if needed as part of a build process):
npm install --save-dev swagger-jsdoc-generator
The configuration file is used to specify which files needs to be scanned to look for jsdoc swagger documentation and other options.
An example of configuration is the following:
All the options supported by swagger-jsdoc (which is the module used internally by the command) are supported.
You can also check out an example of dynamic configuration through node modules.
Here's a brief example about how to document an API:
// src/mySampleApi.js/*** @swagger* /login:* post:* description: Login to the application* produces:* - application/json* parameters:* - name: username* description: Username to use for login.* in: formData* required: true* type: string* - name: password* description: User's password.* in: formData* required: true* type: string* responses:* 200:* description: login*/app;
Then you need to have
mySampleApi.js in your
conf.json configuration file:
Finally you can run the command to produce the swagger definition:
which will produce the following output:
Everyone is very welcome to contribute to this project. You can contribute just by submitting bugs or suggesting improvements by opening an issue on GitHub.
Licensed under MIT License. © Luciano Mammino.