前后端对接文档收集

[liuanxin]

后端在 web 层定义好相关的说明并运行就可以直接查看文档

这是一个 Java web 项目, 基于 spring mvc, 项目地址: https://github.com/liuanxin/api-document

在用 swagger & ui 的过程中, 遇到了一些问题(查看返回的数据结构需要切屏, 无法处理 map 等), 于是新写的一个用来生成前后端对接文档的小项目

主要有四个注解: 分组(模块)、接口、接口中的参数 和 返回. 接口可以被收集在多个分组(模块)中, 可以定义全局的响应说明也可以在单个接口上标明, 返回字段说明直接嵌入在示例的 json 字符串中(也可以单独罗列, 默认是嵌入中其中, 这样在看到返回字段的同时就能知道其意义, 如果类型过大单独罗列在下面需要切屏, 这样容易出现思维跳跃), 参数和返回如果是枚举类型会自动收集每个项进行文档显示, 可以直接在网页上请求后台接口(上传文件还不行, 请使用 postman 等工具)

效果如下: https://raw.githubusercontent.com/liuanxin/image/master/api.png
在线示例: https://liuanxin.github.io/api-info-example.html

[ruanyf]

收入第 46 期。