swagger-jsdoc

Document your code and keep a live and reusable OpenAPI (Swagger) specification. This specification can be the core of your API-driven project: generate documentation, servers, clients, tests and much more based on the rich OpenAPI ecosystem of tools.

Goals

swagger-jsdoc enables you to integrate Swagger using JSDoc comments in your code. Just add @swagger on top of your DocBlock and declare the meaning of your code in YAML complying to the OpenAPI specification. If you prefer to keep some parts of your specification aside your code in order to keep it lighter/cleaner, you can also pass these parts as separate input YAML files.

swagger-jsdoc will parse the above-mentioned and output an OpenAPI specification. You can use it to integrate any server and client technology as long as both sides comply with the specification.

Thus, the swagger-jsdoc project assumes that you want document your existing/living/working code in a way to "give life" to it, generating a specification which can then be fed into other Swagger tools, and not the vice-versa.

If you prefer to write the OpenAPI specification first and separately, you might check other projects facilitating this, such as

• swagger-editor
• swagger-node

Supported versions

• OpenAPI 3.x
• Swagger 2.0

To make sure your end specification is valid, do read the most up-to date official OpenAPI specification.

Installation

$ npm install swagger-jsdoc --save

Or using yarn

$ yarn add swagger-jsdoc

Quick Start

Get started by documenting your code.

Note that swagger-jsdoc uses node glob module in the background when taking your files. This means that you can use patterns such as *.js to select all javascript files or **/*.js to select all javascript files in sub-folders recursively.

Paths provided are relative to the current directory from which you execute the program.

Examples

There are plenty of examples you can use to start off:

• example: contains an example app with version 2 of the specification. It will give you an idea how to annotate your comments in order to include them in the output specification.
• test/cli: CLI tests you can read to get ideas about the available functionalities of the CLI. (apart from the obvious help menu)
• test/example: various assets for tests you can also re-use for starting definitions, routes, etc.

CLI

On top of the Node API, there is also a command line interface.

Reporting issues

Before submitting new issues, please make sure you first search for existing such. It is quite possible that the topic you would like to bring up has been discussed already.

In case of an issue which hasn't been considered yet, please include as much information as possible about the issue. This will help maintainers and other users relate to your problem at hand.

For instance:

• Describe what you were doing when the issue appeared.
• Add a set of steps to reproduce your issue.
• Include screenshots.
• Give examples on expected vs actual behavior.

Contributing

• Fork the project and clone it locally.
• Create branches for each separate topic. Any standard you are used to follow for semantic commit messages will be highly appreciated.
• Comment your code as if you are going to maintain it in the future.
• Use the rich set of unit tests as an example and add your unit tests as well. This will not only enable you to programatically reproduce your fix faster than setting up an application, but it will also make you super cool! :)
• Push to your changes to the origin of your repository and create a new pull request towards the upstream master.

Thank you!