国内外有哪些优秀的接口文档工具值得推荐？

本文共计1253个文字，预计阅读时间需要6分钟。

接口文档是规范整个开发项目流程的文档，前后端开发需在项目初期定义接口规范并形成文档，测试人员需对接口文档进行功能测试和接口测试。

接口文档是贯穿整个开发项目流程中的规范，前后端开发需要在开发前期进行接口定义并形成文档，测试人员在功能测试和接口测试的环节也需要对这些接口文档进行测试。

然而随着开发版本迭代，很多接口发生了变化或者被废弃，而开发后期几乎不会去更新这种静态文档。因此，我们需要一款接口文档工具对静态文档进行维护。本文会列举与对比两款常用的接口文档工具，希望找到一个长期可维护且轻量便捷的接口文档工具。

这里我们选择国外的 Swagger 与国内的 Eolink 作对比， Swagger 是开发者最常用的接口文档工具之一， Eolink 则是国产接口文档工具中比较有代表性的工具之一。

Swagger ：

Swagger 可以为用户提供生成、描述、调用和可视化 RESTful 风格的 Web 服务。此外，还提供了多种编程语言的前后端分离解决方案。

优势：

1、包含 SwaggerEditor ，它是使用 yaml 语言的 Swagger API 的编辑器，支持导出 yaml 和 Json 格式的接口文件。

2、 Swagger 包含了 SwaggerUI ，它将 Swagger Editor 编辑好的接口文档以 html 的形式展示出来。

3、 Swagger 支持根据定义的接口导出各种语言的服务端或客户端代码。

缺点：

1、由于 Swagger 还不支持自定义接口文档，无法指明某一个功能需要是用什么样的接口，因此对于复杂的功能，像一个功能需要多个模块来配合的情况下，联调测试就会变得十分麻烦。

2、无法测试错误的请求方式与参数，不支持接口的参数分组。

3、 Swagger 的代码侵入性比较强。要让 Swagger 生成接口文档必须要给方法或字段添加对应的注解，是存在代码侵入的。

4、官方文档不够全面。