use jsdoc with openapi/swagger for documentation (feature)

[honkskillet]

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.

[honkskillet]

I can probably do a pull request for this but I'd want to know if you'd even be interested.

[Mosely]

In case the author is looking for additional support for this, I would be interested in seeing this feature added. I'm a big fan of OpenAPI and I think it would be a great addition!