Swagger与其他API文档编写工具

swagger特点

swagger是我见过唯一还算将就的一个API文档制作与展示工具，其实最终都没让我找到一款完美的API文档编写工具。

swagger优点:

• 一个文件就是一个文档

• 只针对API，而不针对特定的语言的API，很多自动生成API的工具基本都是只针对特定的API的
• 支持Json和yaml来编写API文档，并且支持导出为json、yaml、markdown等格式
• 如果编写好了API了，可以自动生成相应的SDK，没错，可能你的API接口代码还没有开始写，它就能帮你制作相应的SDK了，而且支持几乎所有主流编程语言的SDK
• 支持自动生成大量主流编程语言/框架的server端
• 界面清晰，无论是editor的实时展示还是ui的展示都十分人性化，其他的API编写工具基本上都做不到这一点，如果自己仅仅用markdown来编写，又要纠结该如何展现，十分痛苦。
• 官网有直接的demo，甚至都可以不用自己搞一套服务器

swagger缺点:

• 貌似无法更改主题
• 中英文的文档都比较少，其主要原因应该是官网的文档本身就不完善，只有针对不同模块儿的介绍，却没有针对具体用户的文档
• yaml文件只能和API项目本身放在一起，这一点暂时还不知道有什么解决方案

其他的API文档编写工具

Apizza

• 外观模仿postman，但是只有网页版，必须谷歌浏览器并且必须安装插件，不开源，不能确定以后是否收费
• 由于外观模仿postman，所以ui上还是不大满意
• 能够自定义环境变量，并且可以不同的环境不同的环境变量
• 拥有团队协作功能，并且有一定的权限管理功能
• 可直接在接口处编写文档，并且能够导出HTML文档，导入Postman Json或者Swagger Json
• 偶尔会有缓存没有清理的问题
• 没有mock server的功能

APIBlueprint

• 自定义markdown语法，用markdown来编写
• 由于自定义了太多的语法，个人认为最后的markdown文件非常混乱，因为很多时候多空格多空行不会影响结果
• 也能生成mock server
• 界面美观，但是不是很直观
• 能够导出markdown和yaml

RAP

• 淘宝出品，Github上start数4000+
• 可以在公司内部搭建，不同的团队都可以在上面创建团队文档和分组
• 不能定义GET、POST、PUT、DELETE之外的请求
• Model不能共享，写了一个地方另外一个地方还要写
• 只能定义200的响应，无法定义请求头、请求格式和相应格式
• 网页直接用js生成mock数据
• 界面有些地方好看，有些地方很丑。。。
• 只能导出为没有样式的html