nodejs 搭建 swagger 文档

第一步 初始化文档安装依赖

1. 初始化项目

npm init -y

2. 安装所需要的依赖

   npm install express swagger-jsdoc swagger-ui-express --save

第二步 定义入口文件 和路由文件

1. 设置index文件

   const path = require("path");
   const express = require("express");
   const swaggerJsdoc = require("swagger-jsdoc");
   const swaggerui = require("swagger-ui-express");
   
   const app = express();
   
   // 定义router
   const userRouter = require("./routers/users");
   app.use("/users", userRouter);
   
   const options = {
     definition: {
       openapi: "3.0.1",
       info: {
         title: "项目名称",
         version: "1.0.0",
         description: `
           欢迎使用每天
           阿斯顿撒旦
           爱上的自行车在吃早餐
         `,
       },
     },
     apis: [path.join(__dirname, '/routers/*.js')],
   };
   
   // 定义swagger 访问的路由
   const swaggerSpec = swaggerJsdoc(options);
   app.use("/api-docs", swaggerui.serve, swaggerui.setup(swaggerSpec));
   
   app.listen(3000, () => {
     console.log("启动服务");
   });
   
   

2. 设置router文件

   const express = require("express");
   const router = express.Router();
   
   /**
    * @swagger
    * /users/hello:
    *  get:
    *    tags:
    *      - 打招呼
    *    summary: hello 打招呼方法
    *    description: 打招呼方法的详细描述
    *    parameters:
    *      - name: name
    *        description: 用户名字
    *        in: query
    *        required: true
    *        type: string
    *    responses:
    *      200:
    *        description: 成功返回 world
    */
   router.get("/hello", (req, res) => {
     const name = req.query.name;
     res.send(`hello ${name}`);
   });
   
   module.exports = router;