目录
前文
-
无关api设计,记录对api约定和文档管理
-
api文档约定问题:
文档编写麻烦 变化则需更新文档 api不可调试 不可流通主流工具
-
记录自己解决思路
准备
适用场景
- 约定api
- api调试
- 导出文档
- 导入postman等主流平台
主流支持
- 文档格式 doc/markdown/pdf/html/swagger.json
- 调试模式 swagger-ui/postman
- 软件平台 yapi/swagger/postman
思路
1. 采用openapi规范编写api文档,具体采用swagger对其的实现,采用代码既文档的管理方式
优点:
api文档格式为通用规范,流通性强.
swagger提供便捷的ui和编辑器,并且流通于主流软件.
局限:
api文档编写成本较高,需要框架支撑其便捷性.
语言 | 框架 | 功能 |
---|---|---|
java | swagger-ui | 注解生成swagger.json |
go | go-swagger | 注释生成swagger.json |
python | flasgger | flask使用注释生成swagger.json |
其他 | swagger-edit | 提供swagger.json编辑器 |
效果
2. 采用swagger-ui来管理swagger文档,使用swagger增强框架Knife4j
优点:
swagger-ui为swagger提供基础的api调试功能
knife4f可以提供swagger文档管理,补强文档导出功能/调试功能
结合第一点框架支持,自带swagger-ui
局限:
无法定制化处理
效果
3.使用swagger.json 流通主流平台,例如postman.
优势: 文档即测试
局限: postman暂时不能直接反向生成swagger.json
效果
相关资源
docker离线swagger 使用localhost:8080访问
扫描二维码关注公众号,回复:
13466841 查看本文章
![](/qrcode.jpg)
docker run --name swagger -p 8080:80 swaggerapi/swagger-editor
docker离线Knife4j 使用localhost:8888/doc访问
I:.
└─knife4
│ app.yml
│
└─data
swagger.json
server:
port: 8888 #启动端口
knife4j:
enableAggregation: true
disk: # 使用静态文件格式。还支持在线模式请自行研究
enable: true
routes:
- name: GOK # 文档名称
location: /app/data/swagger.json #api文档相对路径
docker run --name knife4j -p 8888:8888 -v /i/knife4/app.yml:/app/app.yml -v /i/knife4/data:/app/data - xiaoymin/knife4j