Share-API 更好用的 Swagger 文档视图工具

2,260 阅读1分钟
Swagger 是个非常强大的工具,将生成文档的成本降到很低。
但是 SwaggerUI 部分界面和交互就有些难用了。
例如目前版本查看每一级模型是要一层层点开的。
特别是前端大部分无需关注后端模型的情况下,可能一目了然的观察接口整体 response 是个更好的选择。
于是基于以上场景写了一个 Swagger 的 UI 解析工具,只兼容 openapi 2.0 规范


工具界面

功能与特性
  1. 按照 Tag 分类,左侧展示当前项目的所有 tags
  2. 支持搜索,目前支持全项目搜索,不单单是当前项目
  3. 支持多项目配置
  4. 支持项目的公开和私有的配置
  5. 支持配置 ip 白名单,白名单的 ip 地址可以直接访问私有配置
  6. 支持 私有配置的密码修改,默认 123456
  7. enum 以一个更加友好的方式展示
快速开始
  1. npm 安装
npm i @shuangren/share-api
yarn add @shuangren/share-api
2. 创建 index.js 文件
// index.js
const ApiDoc = require('@shuangren/share-api');
const doc = new ApiDoc();
doc.start();
3. 启动
node index.js
默认启动在 8081 端口


扩展配置

通过 config 设置快速配置项
  1. dataPath后台配置接口列表的存储文件路径 , 默认路径为dist/server
  2. password访问私有项目的密码, 默认为123456
  3. port默认启动端口为 8081
  4. ipList直接访问私有项目的IP白名单列表, 默认为[]
完整配置示例
const ApiDoc = require('@shuangren/share-api');
const doc = new ApiDoc();
doc.config({
  port: '3001',
  password: 'abc123',
  dataPath: '/var/demo/data.config'
  ipList:[
    '192.168.1.111',
    '21.221.1.111'
  ]
});
doc.start();
某些情况下对 Swagger.json 的解析可能会崩溃,若发现此问题请Issue 告知