接口又多又杂怎么办？试试这样管理 API 接口文档！

[scarqin]

API 接口在设计时往往需要编写大量的文档，而且编写完成后往往需要根据实际情况，经常改动文档，这使得文档编写维护工作量相对较大，这让很多的开发者都很头疼。

此外，伴随着接口版本的迭代开发，接口文档也需要同步更新。而且接口开发完成以后，做接口测试会十分不方便，要是遇上接口数量多、参数负载的情况，那不仅不方便，测试工作量会重上加重。

我们还经常会因为交付周期的原因，需要接入一个第三方的库，而第三方的库通常都存在文档老旧，文档不够全面等等或多或少的问题。那这个问题相比于没有文档，对程序员来说更加难以棘手。因为会造成：我们需要的接口不在文档上，文档上的接口不存在库里，又或者是少了一行关键的代码。

以上的问题我都有遇到过，后来还是找到了一些工具如 eolinker 解决了这些问题，在这里分享一下我的经验。

1、接口信息清晰完善

没有文档的库，就好比一个黑盒，我们无法预期它的正常行为。输入了一个 A，预期返回的是一个 B，结果它什么也没有。有的时候，还抛出了一堆异常，导致你的应用崩溃。 而接口信息模糊冗杂，不但加大了开发人员理解的难度，还增加了无谓的沟通成本，拖延项目进度。 为此，我们在编写接口时，应考虑完善，接口录入信息清晰有条理，避免含糊不清的用词和参数。

2、接口文档更新及时

随着接口版本的迭代开发，接口信息有所变化，旧文档已经不能满足接口的要求，开发者可以通过对相应接口文档的接口操作，根据现有接口信息进行重新录入，快速保存为接口的新文档。

3、接口操作历史可溯源

类似 gitHub，接口文档的每一次改动历史应清晰记录下来。在后期接口管理和维护上，通过对操作历史的查看，开发者可以了解到每次改动的目的和内容，进而科学管理接口。 eolinker AMS 记录了接口文档近十次的操作历史，支持接口历史一键回溯功能，降低了成员对接口文档误操作的风险。

4、成员权限有所限制

在项目开发中，由于每个团队成员在项目中担任的角色不同，他们对接口文档应有不同的操作权限，以确保相关接口文档的完整性和安全性。 eolinker AMS 提供了灵活的权限管理，通过分配适当权限给相应成员，保证开发时文档不被无关人员篡改。

5、接口测试同步完成

编写完接口文档后，为验证接口返回值是否符合接口文档所描述的预期结果，开发者们需要对接口进行测试。 eolinker AMS 提供接口本地一键化测试功能，只要将信息录入 eolinker 接口管理平台，你将会省去将接口信息重新复制到测试工具的操作。你只需要点击测试页面，输入测试参数值，便可完成测试。

当然，它还提供 mock 测试功能，通过设置假数据以验证接口的可行性。

[windflyme5]

要是能支持 poseman 直接转换文档就好了

[winglight2016]

@windflyme5 postman ？有 postman 还需要转换文档吗？

[gavin6liu]

这个后台是用啥做的

[Pastsong]

Swagger(Open API), Postman, Paw, API Blueprint 等赞了这个帖子

[xiao6zi]

apizza 这个可以 转换文档

[yejinmo]

搭车问一下，支持 WebSocket(JSON 格式) 的接口管理有什么

[mingyun]

搜了下 居然是 PHP 开发 还有开源版 https://www.eolinker.com/#/os/download

[allenhu]

Swagger 等赞了这个帖子

[dashenbibi]

早就想分享了~团队正在用~eolinker 在接口管理算是国内第一了吧？

[dashenbibi]

@windflyme5 看看这个 https://www.v2ex.com/t/402307#reply0

[vocalman]

我也是在用，这个支持文档转换的

[xiubao]

可以看下这个管理工具，免费开源+接口自动化测试，可线下部署
线上部署： http//doclever.cn
开源地址： https://github.com/sx1989827/DOClever

[muxuClover]

果然在这里找到了这篇文章，这是做接口管理的

[scarqin]

@mingyun 是的