Swagger

swagger setting

const swaggerJsDoc = require("swagger-jsdoc")
const swaggerUi = require("swagger-ui-express")

module.exports = app => {
  // Extended: https://swagger.io/specification/#infoObject
  const swaggerOptions = {
    swaggerDefinition: {
      info: {
        version: "1.0.0",
        title: "Customer API",
        description: "Customer API Information",
        contact: {
          name: "Amazing Developer",
        },
        servers: [`${process.env.HOST}:${process.env.PORT}`],
      },
    },
    // ['.routes/*.js']
    apis: ["./router/*.js", "./controllers/*.js"],
  }

  const swaggerDocs = swaggerJsDoc(swaggerOptions)
  app.use("/swagger", swaggerUi.serve, swaggerUi.setup(swaggerDocs))
}

specify server url and directories that contains swagger tagged document, as in apis above. create route for swagger document like "/swagger" as above...

swagger jsdocs tag

/**
 * @swagger
 * /customers:
 *  get:
 *    description: Use to request all customers
 *    responses:
 *      '200':
 *        description: A successful response
 */
app.get("/customers", (req, res) => {
  res.status(200).send("Customer results")
})
/**
 * @swagger
 * /customers:
 *    put:
 *      description: Use to return all customers
 *    parameters:
 *      - name: customer
 *        in: query
 *        description: Name of our customer
 *        required: false
 *        schema:
 *          type: string
 *          format: string
 *    responses:
 *      '201':
 *        description: Successfully created user
 */
app.put("/customer", (req, res) => {
  res.status(200).send("Successfully updated customer")
})

It's very convenient and inituitive to tag and edit later. Just add comment above each apis or create seperate documents for comments.