use jsdoc with openapi/swagger for documentation (feature) #233
Description
I suggest consider using openAPI 3.0 for document comments. (Or possibly an option of choosing btwn the two?)
At least according to this slant comparison, jsdoc is the most popular javascript documentation tool. https://www.slant.co/topics/5104/~javascript-documentation-tools
The really cool thing would be to use it with swagger/openApi 3 ui explorer.
So a jsdoc documentation comment would look like...
/**
* @swagger
* /user:
* post:
* tags:
* - User
* description: Save user
* produces:
* - application/json
* parameters:
* - name: user
* description: User object
* in: body
* required: true
* responses:
* 200:
* description: Return saved user
*/
then in the express service file you could add just a few lines of code.
const openapiJSDoc = require('openapi-jsdoc')
const swaggerUi = require('swagger-ui-express');
//...
// Initialize openapi-jsdoc -> returns validated OpenAPI spec in json format
const api = openapiJSDoc({
definition: {
// info object, see https://swagger.io/specification/#infoObject
info: {
title: 'Example app', // required
version: '1.0.0', // required
description: 'A sample API for example app'
}
},
// Paths to the API docs
apis: ['./src/api/*/index.js']
})
// Server swagger at <apiurl>/docs using swagger-ui-express
app.use('/docs', swaggerUi.serve, swaggerUi.setup(api));Besides giving you a url with the documentation, this also allows you to construct GET, POST, etc requests to your api right in the browser, and even set tokens for stuff like Auth.