乐趣区

关于文档:现在的程序员真是越来越懒了Api-文档都懒得写程序员Api工具惯的

jiezi

对于大多数程序员不爱写文档问题，我感觉能够从两个方面去拆解：主观原因、客观原因。

1. 主观 – 工夫紧工作重，需要变动快

需求方每次都是紧急需要，老板每次都要求麻利开发，疾速响应。
按时交付的压力曾经让大多数程序员不堪重负，更别提写代码的同时同步保护文档了。而不写文档，或者糊弄文档又不影响开发进度。尤其是互联网公司，需要变动十分快，代码不停的迭代，文档来不及更新，和理论代码差别很大。天天加班做需要了，哪来的工夫写文档。

2. 主观 – 缺乏经验，写作艰难

正是因为长期不写文档或者轻易一些，当须要去写的时候，发现无从下笔，写作可太难了!!!

而接口文档的要求相对来说较高，不仅须要内容详实，把问题讲清楚，还须要有清晰的层级构造，让其余读者疾速获取到须要的信息，这对常常写代码不足文档教训的咱们来说，自身也是一项挑战。还记得写降职问难 PPT 的苦楚局面吧~

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

对于写文档这件事件来说，往往短期高估文档的重要性，长期低估文档的重要性。短期以我的项目按时交付为主，我的项目细节也都还烂熟于心，然而长期来说，随着大脑的记忆内存被逐步回收，当再次迭代之前的代码时，甚至有人员变更时，不足文档的局部往往成为黑盒子，与其花大量工夫去摸索解密他人的代码，还不如整体重构来得快！
于是，咱们仿佛陷入了工作永远做不完的怪圈：

针对文档治理的问题，Eolink 提供了完满的解决方案，满足了 Api 文档治理的 4 个弱小能力。

  • 依据代码生成文档
  • 便捷的调试体验和主动生成测试数据
  • 反对多场景分享文档
  • 标准规范的 API 管理工具

同时，在 API 研发治理平台 中，也能够通过三种形式来一键创立 API 文档：

  • 手动创立 API 文档
  • 关联我的项目与代码仓库主动创立文档
  • 关联我的项目与 Swagger URL 主动创立文档

3.1 手动创立 API 文档

API 研发治理平台提供了十分全面的 API 文档格局，可能具体记录您的 API 信息。这种形式适宜所有用户，也是我鼎力举荐的形式。

👉官网体验链接：https://www.eolink.com/

操作方法：登录 Eolink 后，在我的项目详情页点击左侧 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 配置（其余代码仓库也反对，详见官网）

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

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

零正文生成文档，装置和配置办法：

  1. 在 IDEA 插件市场中搜寻“apikit”，找到“Eolink ApiKit”插件装置即可。
  2. 目前仅反对 2020.03-2022.03 版本的 IDEA
  3. 首次上传须要填写配置信息，配置信息我的项目之间独立

  4. 配置信息获取路径：SpaceKey 和 ProjectHashKey 通过 Eolink 的 web 版 url 中的参数获取，token 填本人 Eolink 帐号，服务器填指标服务器域名。

    • 如果应用的是 SaaS，server 后须要加上 /api
    • 如果应用的是公有云版本，须要在 server 后加上 index.php
    • token 目前应用的是集体帐号（邮箱 / 手机 / 帐号）
    • StringType 决定出入参的字符串类型，只有参数名一开始就是恪守驼峰标准才会发现扭转，预览窗口可看到变动后果

弱小的 Eolink，不仅帮咱们解决了写文档，治理文档，迭代变更沟通协调等诸多问题。还有许许多多的惊喜，留给你本人摸索吧！！

退出移动版