With this library, you can document your express endpoints using swagger OpenAPI 3 Specification without writing YAML or JSON. You can write jsdoc comments on each endpoint, and the library is going to create the swagger UI.
This library assumes you are using:
npm i express-jsdoc-swagger
const express = require('express');
const expressJSDocSwagger = require('express-jsdoc-swagger');
const options = {
info: {
version: '1.0.0',
title: 'Albums store',
license: {
name: 'MIT',
},
},
security: {
BasicAuth: {
type: 'http',
scheme: 'basic',
},
},
filesPattern: './**/*.js', // Glob pattern to find your jsdoc files
swaggerUIPath: '/your-url', // SwaggerUI will be render in this url. Default: '/api-docs'
baseDir: __dirname,
};
const app = express();
const PORT = 3000;
expressJSDocSwagger(app)(options);
/**
* GET /api/v1
* @summary This is the summary or description of the endpoint
* @return {object} 200 - success response
*/
app.get('/api/v1', (req, res) => res.json({
success: true,
}));
app.listen(PORT, () => console.log(`Example app listening at http://localhost:${PORT}`));- Basic configuration
const options = {
info: {
version: '1.0.0',
title: 'Albums store',
license: {
name: 'MIT',
},
},
security: {
BasicAuth: {
type: 'http',
scheme: 'basic',
},
},
filesPattern: './**/*.js', // Glob pattern to find your jsdoc files
baseDir: __dirname,
};- Components definition
/**
* A song type
* @typedef {object} Song
* @property {string} title.required - The title
* @property {string} artist - The artist
* @property {number} year - The year - double
*/- Endpoint that returns a
Songsmodel array
/**
* GET /api/v1/albums
* @summary This is the summary or description of the endpoint
* @tags album
* @return {array<Song>} 200 - success response - application/json
*/
app.get('/api/v1/albums', (req, res) => (
res.json([{
title: 'abum 1',
}])
));- Basic endpoint definition with tags, params and basic authentication
/**
* GET /api/v1/album
* @summary This is the summary or description of the endpoint
* @security BasicAuth
* @tags album
* @param {string} name.query.required - name param description
* @return {object} 200 - success response - application/json
* @return {object} 400 - Bad request response
*/
app.get('/api/v1/album', (req, res) => (
res.json({
title: 'abum 1',
})
));You can find more examples here, or visit our documentation.
Briam Martinez Escobar 💻 |
Kevin Julián Martínez Escobar 💻 |
This project follows the all-contributors specification. Contributions of any kind welcome!