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.
swagger-jsdoc will parse your documentation from
your actual living code and output an OpenAPI specification 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 working code in a way to "give life" to it, generating a specification which can then be feeded 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
$ npm install swagger-jsdoc --save
Or using yarn
$ yarn add swagger-jsdoc
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.
There is an example app in the example subdirectory. To use it you can use the following commands:
$ git clone https://github.com/Surnet/swagger-jsdoc.git
$ cd swagger-jsdoc
$ npm install
$ npm start
The swagger spec will be served at http://localhost:3000/api-docs.json
You can also use the tool via command line interface. It supports selecting multiple files, recursive subdirectories and watch task for continuous listening of changes in your code.
Note: If there are additions to the swagger definition object ensure that the output object keys comply with the swagger specification. If there are keys that do not comply add them to the excludedSwaggerProperties list in lib/swagger-helpers.js.
v1.9.7 (2017/07/24 17:11 +00:00)
FAQs
Generates swagger doc based on JSDoc
The npm package swagger-jsdoc receives a total of 620,840 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
Fluent Assertions is facing backlash after dropping the Apache license for a commercial model, leaving users blindsided and questioning contributor rights.
Research
Security News
Socket researchers uncover the risks of a malicious Python package targeting Discord developers.
Security News
The UK is proposing a bold ban on ransomware payments by public entities to disrupt cybercrime, protect critical services, and lead global cybersecurity efforts.