你一定要用这个API管理工具，看完你就知道为什么了

news2024/11/26 22:17:43

以下是经常发生在程序员之间的对话：

小张：你知道为什么程序员不喜欢写文档？

小王：因为代码就是最好的文档啊！谁还需要写那些冗长的说明呢？

小张：那你知道为什么程序员也不喜欢别人不写文档吗？

小王：当然了！写文档虽然烦人，但对团队合作和项目维护很重要。

小张：没错！我们需要养成写文档的好习惯。

小王：同意！现在让我们继续码代码吧，然后... 把那个没有文档的项目丢给别人解决！哈哈！

一、程序员不爱写文档？人之常情

程序员为什么不爱写文档？是他们变懒了吗？其实这是人之常情，关于大多数程序员不爱写文档问题，可以从两个方面去拆解：主观原因、客观原因。

1. 客观原因：时间紧，任务重

需求方每次都是紧急需求，老板每次都要求敏捷开发，快速响应。

按时交付的压力已经让大多数程序员不堪重负，更别提写代码的同时同步维护文档了。而不写文档，或者糊弄文档又不影响开发进度。

2. 主观原因：缺乏经验，写作困难

正是由于长期不写文档或者随便一些，当需要去写的时候，发现无从下笔，写作可太难了!!!

而接口文档的要求相对来说较高，不仅需要内容详实，把问题讲清楚，还需要有清晰的层级结构，让其他读者快速获取到需要的信息，这对经常写代码缺乏文档经验的我们来说，本身也是一项挑战。（还记得写晋升答辩 PPT 的痛苦场面吧~ ）

3. 外部原因：需求变化快

尤其是互联网公司，需求变化非常快，代码不停的迭代，文档来不及更新，和实际代码差异很大。天天加班做需求了，哪来的时间写文档。

当然，不写文档的问题也不能责怪程序员，更深层级的原因可能是公司流程、制度、管理等等方面的，这里就不展开说了，请各位领导不要对号入座。

二、写文档这么麻烦，那我们就不写了吗？

对于写文档这件事情来说，往往短期高估文档的重要性，长期低估文档的重要性。 短期以项目按时交付为主，项目细节也都还烂熟于心，但是长期来说，随着大脑的记忆内存被逐渐回收，当再次迭代之前的代码时，甚至有人员变更时，缺乏文档的部分往往成为黑盒子，与其花大量时间去探索解密别人的代码，还不如整体重构来得快！

于是，我们似乎陷入了工作永远做不完的怪圈：

三、自动生成文档，解决一切烦恼

针对文档管理的问题，Eolink Apikit 提供了完美的解决方案，满足了 Api 文档管理的 4 个强大能力。

根据代码生成文档
便捷的调试体验和自动生成测试数据
支持多场景分享文档
标准规范的 API 管理工具

同时，在 API 研发管理平台中，也可以通过三种方式来一键创建 API 文档：

手动创建 API 文档
关联项目与代码仓库自动创建文档
关联项目与 Swagger URL 自动创建文档

3.1 手动创建 API 文档

API 研发管理平台提供了非常全面的 API 文档格式，能够详细记录您的 API 信息。这种方式适合所有用户。

操作方法： 登录 Eolink Apikit后，在项目详情页点击左侧 API 文档功能，进入 API 管理页面，点击 添加 API，会进入 API 创建页面。

私有云产品比线上 SaaS 产品支持更多的 API 协议，比如 TCP、UDP、SOAP、HSF 等。

API 编辑页面中可以填写 API 文档、返回数据、额外说明等信息，您可以通过顶部的标签切换。

3.2 关联项目与 Swagger URL 自动创建文档

API 研发管理平台自动从该地址获取最新 API 文档。这种方式适合之前已经在使用 Swagger，并且倾向于将文档写在代码注解中的用户。但这种方式会带来代码入侵的问题，让代码中加入了许多无关的信息从而增加维护成本。

操作方法： 您可以给项目关联 Swagger 生成的 JSON 文件地址，API 研发管理平台能够远程读取 Swagger JSON 并自动生成 API 文档。进入 API 管理与测试，选择项目，点击左侧栏的其他可以看到 API 文档生成

点击添加来源，在弹窗中选择通过 Swagger URL 生成 API 文档，然后点击下一步：

输入 Swagger 生成的 JSON 地址，注意该 JSON 地址需要能够通过网络访问，并且该地址返回的数据需要是 JSON 类型的数据，否则会提示无法访问该地址。

配置完成后，界面会提示配置完成。此时您可以通过在当前页面页点击同步按钮，或者通过 Open API 触发同步操作。

3.3 关联项目与代码仓库自动创建文档

API 研发管理平台自动从代码仓库中扫描代码注解生成 API 文档。目前这种方式支持 Java 以及 PHP 两种语言。这种方式也会带来代码入侵的问题。

可以给项目关联代码仓库，API 研发管理平台能够远程读取仓库中的代码注解并自动生成 API 文档，能够识别 Swagger 2.0、OpenAPI 3.0 的代码注解格式。当然，为了标准化管理，新的规范都用 OpenAPI 3.0 了。

看起来，目前支持的仓库类型有：Github、Gitlab、码云等等。

操作方法： 进入项目页，点击其他，再点击 API 文档生成添加来源，在弹窗中设置需要扫码的代码仓库，点击立即同步即可。

GitHub 配置（其他代码仓库也支持，详见官网）

配置项	说明
代码仓库类型	选择 Github
代码仓库地址	默认填写 Github 官网
用户名	Github 账户名称
仓库名	Github Repository 仓库名称
访问私钥	仓库私人令牌在 GitHub Repository 的 Settings->Developer settings->Personal access tokens 中生成
需要扫描的分支	默认为 master 分支，您也可以选择实际需要扫描的代码分支
需要扫描的 API 目录路径	API 层相关代码的存放路径
需要扫描的数据结构目录路径	数据结构相关配置信息的存放路径

3.4 基于IDEA插件，零注释生成文档

更加牛逼的自动化生成方式是：“基于IDEA插件零注释生成文档”。

零注释生成文档，安装和配置方法：

在IDEA插件市场中搜索“Apikit”，找到“Eolink ApiKit”插件安装即可。
目前仅支持2020.03-2022.03版本的IDEA
首次上传需要填写配置信息，配置信息项目之间独立
配置信息获取途径：SpaceKey和ProjectHashKey通过Eolink的web版url中的参数获取，token填自己Eolink帐号，服务器填目标服务器域名。
1. 如果使用的是SaaS，server后需要加上/api
2. 如果使用的是私有云版本，需要在server后加上index.php
3. token目前使用的是个人帐号（邮箱/手机/帐号）
4. StringType决定出入参的字符串类型，只有参数名一开始就是遵守驼峰规范才会发现改变，预览窗口可看到变化结果