Vscode niuhe 插件使用教程(4) - 生成 swagger.json

思无邪2100
157 阅读2分钟

官方教程已经上线, 请访问: niuhe.zuxing.net

niuhe 插件默认不生成 swagger.json 文件, 需要生成 swagger.json 文件需在 niuhe/.config.json5 配置项 langs 中添加 docs, 如

{
	langs: ['ts','docs']
}

生成代码时会将 swagger 信息保存于 docs/swagger.json 文件中。

更多 swagger 信息

生成的 swagger 格式为 2.0 版本, 需要定制更多信息, 需要在 niuhe 文件夹下添加 docs.json5 文件对其进行个性化定制。完整的配置如下(所有选项都是可选的, 配置内容可在插件细节中获取)

{  
    info: {  
        title: "牛河",  
        description: "牛河接口文档",  
        license: { // 默认不生成 license 字段  
            name: "MIT",  
            url: "github", // 证书地址  
        },  
        contact: { // 联系方式  
            email: "xxx.qq.com",  
        },  
        version: "3.0.0",  
    },  
    schemes: ["http", "https"],  
    consumes: ["application/x-www-form-urlencoded"], // 定义请求的 Content-Type方式, 默认为: application/x-www-form-urlencoded  
    produces: ["application/json"], // 定义返回的 Content-Type, 默认为: application/json  
    host: "", // 默认为空  
    basePath: "", // 默认为空  
    title: "牛河",  
    security: { // 支持的 验证方式  
        bearer: { // 这里为 bearer 的例子  
            type: "apiKey",  
            name: "Authorization",  
            in: "header", // bearer 放在 header 中  
        },  
    },  
    tags: { // tags 为 API 分组标签, 为 /model/view/method/ 三段结构中的 view 名称, 相当于给 API 分组  
        system: '系统API',  
    },  
    format: false, // 是否格式化 json 输出, 默认为 true  
    rsp: {  
        result: 'result', // 自定义 protcol 时修改 {result, data} 中的 result  
        data: 'data', // 自定义 protcol 时修改 {result, data} 中的 data  
    }  
}

每个属性的用法和含义都在 json5 文件中进行了注释，这里我们以项目 admin-core-niuhe 为例演示。

案例展示

这里我们只需对生成的 swagger 进行分组(tags）, 因此只需自定义 tags 即可

{
  info: {
    title: "admin-core api 文档",
    version: "1.0.0",
    description: "基于 Vue3 + Vite5+ TypeScript5 + Element-Plus + Pinia 等主流技术栈构建的免费开源的后台管理前端模板 go 版后端管理程序 api 文档",
    license: {
      name: "MIT License",
      url: "https://github.com/ma-guo/vue3-element-admin/blob/main/LICENSE",
    },
  },
  security: {
    // 支持的 验证方式
    bearer: {
      // 这里为 bearer 的例子
      type: "apiKey",
      name: "Authorization",
      in: "header", // bearer 放在 header 中
    },
  },
  tags: {
    auth: "登录认证",
    dept: "部门管理",
    dict_types: "字典类型",
    dict: "字典管理",
    files: "文件管理",
    menus: "菜单管理",
    roles: "角色管理",
    users: "用户管理",
    vendor: "存储提供商",
  },
}
avatar
文章
阅读
粉丝