swagger-jsdoc
Advanced tools
swagger-jsdoc is a Node.js library that allows you to integrate Swagger/OpenAPI documentation into your Express.js or other Node.js applications. It generates the Swagger specification based on JSDoc comments in your code, making it easier to maintain and update API documentation.
Generate Swagger Documentation
This feature allows you to generate Swagger documentation from JSDoc comments in your code. The `options` object specifies the OpenAPI version, API info, and the files containing the JSDoc comments.
const swaggerJsdoc = require('swagger-jsdoc');
const options = {
definition: {
openapi: '3.0.0',
info: {
title: 'Express API with Swagger',
version: '1.0.0',
},
},
apis: ['./routes/*.js'], // files containing annotations as above
};
const swaggerSpec = swaggerJsdoc(options);Integrate with Express
This feature demonstrates how to integrate Swagger UI with an Express application. The Swagger documentation is served at the `/api-docs` endpoint.
const express = require('express');
const swaggerUi = require('swagger-ui-express');
const swaggerJsdoc = require('swagger-jsdoc');
const app = express();
const options = {
definition: {
openapi: '3.0.0',
info: {
title: 'Express API with Swagger',
version: '1.0.0',
},
},
apis: ['./routes/*.js'],
};
const swaggerSpec = swaggerJsdoc(options);
app.use('/api-docs', swaggerUi.serve, swaggerUi.setup(swaggerSpec));
app.listen(3000, () => {
console.log('Server is running on port 3000');
});JSDoc Annotations
This feature shows how to use JSDoc annotations to document an API endpoint. The annotations provide metadata about the endpoint, such as the HTTP method, summary, and response schema.
/**
* @swagger
* /users:
* get:
* summary: Retrieve a list of users
* responses:
* 200:
* description: A list of users
* content:
* application/json:
* schema:
* type: array
* items:
* type: object
* properties:
* id:
* type: integer
* name:
* type: string
*/
app.get('/users', (req, res) => {
res.json([{ id: 1, name: 'John Doe' }]);
});swagger-ui-express is a middleware for Express.js that serves auto-generated Swagger UI. It is often used in conjunction with swagger-jsdoc to serve the generated Swagger documentation. While swagger-jsdoc focuses on generating the Swagger specification, swagger-ui-express focuses on serving it in a user-friendly interface.
openapi-generator is a tool that can generate client libraries, server stubs, API documentation, and configuration from an OpenAPI Specification. Unlike swagger-jsdoc, which generates the OpenAPI spec from JSDoc comments, openapi-generator takes an existing OpenAPI spec and generates code and documentation from it.
redoc is a tool for generating API documentation from OpenAPI specifications. It provides a customizable and responsive HTML documentation. Unlike swagger-jsdoc, which generates the OpenAPI spec, redoc focuses on rendering the documentation from an existing spec.
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.
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
You can use this package with a webpack plugin to keep your swagger documentation up-to-date when building your app:
To make sure your end specification is valid, do read the most up-to date official OpenAPI specification.
$ npm install swagger-jsdoc --save
Or using yarn
$ yarn add swagger-jsdoc
Before you start writing your specification and/or documentation, please keep in mind that there are two fundamental concepts you need to wrap you head around when working with swagger-jsdoc - definition object and input APIs.
Definition object maps to OpenAPI object. This is where you would add information about your API and any root-level properties. Definition object is a required parameter.
Input APIs are any files which you pass as arguments to the program in order to extract information about your API. For instance, these could be .js files with JSDoc comments or .yaml files directly. This parameter is also required.
There are a few ways by which you can pass these 2 required arguments:
When using the CLI:
apis property in your definition object.When using the Node API:
apis in your options object.For example, given the following module export for a definition object:
// Taken from example/v2/swaggerDef.js
module.exports = {
info: {
// API informations (required)
title: 'Hello World', // Title (required)
version: '1.0.0', // Version (required)
description: 'A sample API', // Description (optional)
},
host, // Host (optional)
basePath: '/', // Base path (optional)
};
One way you can make use of this definition is by using the CLI as following:
$ swagger-jsdoc -d example/v2/swaggerDef.js example/v2/route*.js
If you, however, want to skip the arguments and still use the CLI, you will need to update the definition object as following:
// Taken from example/v2/swaggerDef.js
module.exports = {
...
apis: ['example/v2/route*.js'] // <-- We add this property:
basePath: '/', // Base path (optional)
};
And then you will be able to use the CLI as following:
$ swagger-jsdoc -d example/v2/swaggerDef.js
When using the Node API, input APIs come in in the following way:
const swaggerJSDoc = require('swagger-jsdoc');
const swaggerDefinition = {
...
basePath: '/', // Base path (optional)
};
const options = {
swaggerDefinition,
apis: ['./example/v2/routes*.js'], // <-- not in the definition, but in the options
};
const swaggerSpec = swaggerJSDoc(options);
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.
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.On top of the Node API, there is also a command line interface.
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:
Thank you!
v4.1.0 (2020/09/25 10:24 +00:00)
FAQs
Generates swagger doc based on JSDoc
The npm package swagger-jsdoc receives a total of 688,205 weekly downloads. As such, swagger-jsdoc popularity was classified as popular.
We found that swagger-jsdoc demonstrated a not healthy version release cadence and project activity because the last version was released a year ago. It has 4 open source maintainers collaborating on the project.
Did you know?
Socket for GitHub automatically highlights issues in each pull request and monitors the health of all your open source dependencies. Discover the contents of your packages and block harmful activity before you install or update your dependencies.
Security News
PyPI confirms no security flaws were exploited in the Ultralytics supply chain attack and highlights improvements for safer package publishing.
Security News
Research
The Socket Research Team breaks down a malicious wrapper package that uses obfuscation to harvest credentials and exfiltrate sensitive data.
Research
Security News
Attackers used a malicious npm package typosquatting a popular ESLint plugin to steal sensitive data, execute commands, and exploit developer systems.