使用nodejs编写swagger文档

提要

1. 使用nodejs+express写的swagger文档 没有实现example效果
2. swagger有两种编写注释的方式 json跟yaml 但是我搜到的json不太能用 下次再尝试一下
3. 我的swagger是oas 3.0的 好像有些是2.0 这个找教程的时候要看好
4. 有教程写的使用swagger官方库的dist 我试过了 不太行 如果有朋友试了成功的话可以分享给我吗0.0

步骤

1.安装库

npm install swagger-ui-express swagger-jsdoc -S

我的库版本参考:

2.创建中间件

swaggerInstall-swagger注册函数(/utils/swagger)

var path = require("path");
var express = require("express");
var swaggerUi = require("swagger-ui-express");
var swaggerJSDoc = require("swagger-jsdoc");
//author:neversleep
//comment:swagger请求路径：http://localhost:9009/swagger
// 配置 swagger-jsdoc
const options = {
    definition: {
        // 采用的 openapi 版本。***注意该版本直接影响了管网参考版本。
        openapi: "3.0.0",
        // 页面基本信息
        info: {
            title: "茶叶商城", //设置swagger的标题。（项目名称）
            version: "1.0.0", //设置版本
        },
        //设置锁。用于生成swagger文档。(这部分是我抄的 还没明白有什么用0.0)
        // components: {
        //     securitySchemes: {
        //         oauth2: {
        //             type: "oauth2",
        //             flows: {
        //                 authorizationCode: {
        //                     authorizationUrl: "/oauth/dialog",
        //                     tokenUrl: "/oauth/token",
        //                 },
        //             },
        //         },
        //     },
        // },
    },
    // 去指定项目路径下收集 swagger 注释，用于生成swagger文档。
    //这里一定要写路由的地址 不能随便抄!
    apis: [path.join(__dirname, "../../router/**/*.js")],
};
var swaggerJson = function (req, res) {
    res.setHeader("Content-Type", "application/json");
    res.send(swaggerSpec);
};
const swaggerSpec = swaggerJSDoc(options);

var swaggerInstall = function (app) {
    if (!app) {
        app = express();
    }
    // 此路径用于向YApi导入接口文档
    app.get("/swagger.json", swaggerJson);
    // 使用 swaggerSpec 生成 swagger 文档页面，并开放在指定路由。swagger访问前缀
    app.use("/swagger", swaggerUi.serve, swaggerUi.setup(swaggerSpec));
};

module.exports = swaggerInstall;

app.js(注册swagger api)

// swagger
// 使用swagger API 文档
var swaggerInstall = require('./utils/swagger')
swaggerInstall(app)

api.js

/**,
 * @swagger
 * /api/hello: #一定要写完整路径 我使用路由中间件的时候 加了api前缀
 *    get:
 *      tags: #分类
 *      - 测试
 *      summary: 提交考试答案 #这个接口的提示
 *      produces:
 *      - application/json #返回类型
 *      parameters: #参数以及参数类型
 *      - name: name
 *        in: query
 *        description: 姓名
 *        required: false
 *        type: integer
 *      responses:
 *        200:
 *          description: successful operation 
 *        400:
 *          description: Invalid ID supplied
 *        404:
 *          description: Order not found               
 * */

router.get("/hello", (req, res) => {
    const name = req.query.name;
    res.send({
        hello:`hello`
    });
});

1. 重点在于注释 注释使用的yaml语法(YAML 语言教程 -阮一峰),有官方的editor 照着抄也行其实 每个key的意思可以参考这篇博客

效果:

参考的教程:

1. https://blog.csdn.net/qq_43234632/article/details/113347958
2. https://blog.csdn.net/weixin_40305713/article/details/111921938
3. https://www.jianshu.com/p/31d486c5cfd3

in case 会用到的链接:
YAML 语言教程 -阮一峰
swagger 官方的editor
swagger key中文作用
json写法的博客