程序员真的很懒，你懒得写API文档吗？程序员：用的是Api工具

关于大部分程序员不喜欢写文档的问题，我觉得可以从两个方面来分解：主观原因和客观原因。

1.目标——时间紧任务重，需求变化快

需求方每次都很急，用人单位每次都要求敏捷开发、快速响应。

按时交付的压力压倒了大多数程序员，更不用说编写代码时的文档了。不用写文档，或者在不影响开发进度的情况下胡乱摆弄文档。

尤其是互联网公司，需求变化很快，代码不断迭代，文档来不及更新，与现在的代码有很大区别。每天加班做需求，没时间写文档。

2.主观——没有经验，难写

正是因为很久没有写文档或者是随便写的。当我不得不写的时候，我发现写不下去了。写的太难了！

展开全文

对接口文档的要求比较高。它们不仅要详细、清楚地说明问题，而且还必须具有清晰的层次结构，以便其他读者能够快速获得所需的信息。这对我们这些经常写代码，缺乏文档经验的人很有帮助。也就是说，这本身就是一个挑战。想想写升职答辩PPT的痛苦情景~

当然，不写文档的问题不能怪程序员。

更深层次的原因可以是公司的流程、制度、管理等等，这里就不多说了。领导，请不去你的地方。

对于书写文档，文档的重要性往往在短期内被高估，而在长期内被低估。短期内，项目主要按时交付，项目细节仍处于保密状态。但是长此以往，随着大脑的记忆逐渐恢复，当再次迭代之前的代码，甚至是人员变动的时候，就会出现文档缺失的情况。

通常有一个黑匣子。与其花大量时间去探索和破译别人的代码，不如整体重构！

结果，我们似乎陷入了永无休止的工作的恶性循环：

针对文档管理的问题，Eolink提供了完善的解决方案，实现了API文档管理的四大强大能力。

生成代码文档

便捷的调试体验，自动生成测试数据

支持多场景文档共享

标准化的API管理工具

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

手动创建API文档

自动为关联项目和代码存储库创建文档

将项目与SwaggerURL相关联以自动创建文档

3.1创建手动API文档

API研发管理平台提供了非常全面的API文档格式，可以详细记录您的API信息。

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

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

API编辑页面可以填写API文档、返回数据、附加说明等信息，并可以通过顶部的选项卡进行切换。

3.2关联项目SwaggerURL自动创建文档

API研发管理平台自动从该地址接收最新的API文档。

这种方式适合使用过Swagger，倾向于编写文档和代码注释的用户。但是这种方式带来了代码入侵的问题，在代码中加入了很多不相关的信息，增加了维护成本。

操作方法：可以将Swagger生成的JSON文件地址与项目关联，API研发管理平台可以远程读取SwaggerJSON并自动生成API文档。

进入API管理和测试，选择项目，点击左侧栏的Other，可以看到API文档生成：

点击AddSource，在弹窗中选择GenerateAPIDocumentationviaSwaggerURL，点击Next：

输入Swagger生成的JSON地址。

注意JSON地址必须是网络可访问的，地址返回的数据必须是JSON类型的数据，否则会询问地址不可访问。

配置完成后，界面会提示配置完成。此时可以点击当前页面的同步按钮，也可以通过OpenAPI触发同步操作。

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

API研发管理平台自动从代码仓库中扫描代码注释，生成API文档。目前该方法同时支持Java和PHP两种语言。这种做法也带来了代码入侵的问题。

代码仓库可以接入项目，API研发管理平台可以远程读取代码仓库中的代码注解并自动生成API文档，可以识别Swagger2.0和OpenAPI3.0的代码注解格式。

当然，为了规范管理，新规范全部使用OpenAPI3.0。

貌似目前支持的仓库类型有：Github、Gitlab、码云等。操作方法：进入项目页面，点击其他，然后点击API文档生成添加源，在弹窗中设置需要扫描的代码仓库，点击立即同步。

GitHub配置（其他代码仓库也支持，具体查看官网）

3.4基于IDEA插件，生成零评论文档

比较强大的自动生成方法是：《基于IDEA插件零评论生成文档》。

零注解生成文档、安装配置方法：

在IDEA插件市场搜索“apikit”，找到“EolinkApiKit”插件并安装。

目前只支持IDEA版本2020.03-2022.03

首次上传必须填写配置信息，配置信息项独立

配置信息获取方式：SpaceKey和ProjectHashKey通过Eolink网页版URL中的参数获取，token填写自己的Eolink账号，server填写目标服务器的域名。

如果你使用的是SaaS，需要在server后面加上/api

如果使用私有云版本，需要在server后面添加index.php

该令牌当前使用个人帐户（电子邮件/手机/帐户）

StringType决定了输入输出参数的字符串类型。

只有当参数名称最初与驼峰规范匹配时，才会检测到更改，并且可以在预览窗口中看到更改结果。

强大的Eolink不仅帮我们解决了文档编写、文档管理、迭代变更沟通协调等诸多问题。惊喜多多，一起来发现吧！

扫码加微信详细咨询太和智慧养老产品和平台服务！

扫码加微信详细咨询太和智慧养老产品和平台服务！

扫码加微信详细咨询太和智慧养老产品和平台服务！