文档即接口 - XJZProxy 提高你的开发、协作效率

[xjz19901211]

官网 https://xjzproxy.xjz.pw/zh-cn

PS: 新版本发布，顺便修改了一下介绍，如果大家有什么建议或意见，欢迎提出，谢谢。

---

主要功能

• 本地 API Mock 基于 YAML 文档，支持动态数据生成
• 自动生成、导出 API 文档
• 自动基于文档对比 API 请求响应数据格式，提前发现有问题的接口
• 根据请求历史生成统计数据
• HTTP/HTTPS/HTTP2/GRPC 代理

我们遇到的问题

通过为了方便合作，在需求确定后，我们会先写一份接口文档给前端，然后前端按文档定义的接口去开发。

在这期间我们可能会遇见很多问题:

1. 结构松散或是没有结构的文档格式，很难去管理、协作，写起来也麻烦
2. 只有文档，自己 mock 各种数据很麻烦，等真实接口好了才方便开发
3. 请求参数格式没按文档来，在个例下正常工作，到复杂的线上就出问题了
4. 后端接口没有文档格式来，在特定情况下前端没有处理而出问题
5. 接口改了，但文档没改，久而久之，文档形同虚设

我们的解决方案

1. 使用 YAML 书写结构化的文档，数据结构可以复用。一个接口甚至可以简单到只需要几行
2. 文档完成后，你就相当于有了一个本地的后端服务器，文档中所有接口可以直接调用
3. 在请求文档接口时，我们会按文档检查请求参数是否与文档定义一致。遇到不匹配的将会有相应提示
4. 在连接上真实服务器时，我们会帮助你检查数据的返回格式是否与文档定义一致。遇到不匹配的将会有相应提示
5. 以上方式让文档主动参与到开发中，将督促使用者去更新文档

Example

一个最简单的项目文档示例

project:
  host: mydomain.com

apis:
  - title: Get a user
    method: GET
    path: /api/v1/users/\d+
    response:
      success:
        http_code: 200
        data:
          id: 1
          name: .t/name

然后就可以通过文档代理来访问了

$ curl http://mydomain.com/api/v1/users/123 --proxy localhost:9898
{"id": 1, "name": "random name"}

当然，你可以在移动设备、浏览器中通过代理地址访问接口。更多文档书写帮助请参考这里

请求参数和文档对不上时，会有提示

GRPC

如果你在使用 GRPC 的话，只要配置好 protobufs 的路径，就可以直接调用接口了。当然，如果你想定制 GRPC 接口返回的数据内容，还是需要在文档中定义好一些数据模板。

Preview

在工具中查看渲染好的漂亮文档也是不能少的。

More

更多功能介绍，可参考官网。欢迎大家试用。

---

有兴趣的朋友可以在这里下载试用（目前只支持 Mac 与 Ubuntu，其它系统以后看情况再折腾了)。

如果需要使用 GRPC 或者需要更多的 API 数量（> 128 ），发邮件到 base64 eGllamlhbmd6aGlAZ21haWwuY29t。我会给发送证书。记得带上标题 "XJZProxy 证书申请"，不然我可能注意不到。

[wssy921]

这个不是和 swagger 的代码生成器很类似。swagger 可以根据 yaml 生成代码，并可以运行

[xjz19901211]

@wssy921 差别还是很大的。 我们是直接根据 yaml 文档来返回数据或是对比请求结果。
然后这份文档你可以使用 git 等工具进行协作管理。

在易用性方面应该好很多。相对 open api 的文档定义，我们的简单很多。当然相应的，目前数据结构可能并没有像 openapi 那边严谨。这方面，以后会看用户需求来再提高。

欢迎试用哟。同时也非常渴望更多的对比意见（因为我也没有深入使用过 swagger ），谢谢