api文档一些思考

前文

1. 无关api设计,记录对api约定和文档管理

2. api文档约定问题：

    文档编写麻烦
    变化则需更新文档
    api不可调试
    不可流通主流工具
   

3. 记录自己解决思路

准备

适用场景

• 约定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

效果

相关资源

swagger.io 官方在线编辑器

docker离线swagger 使用localhost:8080访问

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