为了让大家更能清楚了解 Api 相关往期内容,我写了一个阅读指引:
序号 | 学习路径指引 | 链接 |
---|---|---|
1 | Api -- 连接世界的 Super Star | Api -- 连接世界的Super Star_不吃西红柿丶的博客-CSDN博客 |
2 | 软件吞噬世界,Api 快速入门到放弃 | 软件吞噬世界,Api快速入门到放弃_不吃西红柿丶的博客-CSDN博客 |
3 | Apifox vs Eolink,国内 Api 工具哪家强? | Apifox vs Eolink,国内 Api 工具哪家强?_不吃西红柿丶的博客-CSDN博客 |
4 | 都 2203 年了,还有人使用 word 调试 Api !!! | 活久见:都 2203 年了,你还在使用 word 调试 API_不吃西红柿丶的博客-CSDN博客 |
5 | 现在的程序员真是越来越懒了,api 文档都懒得写!程序员:“api工具惯的” | 现在的程序员真是越来越懒了,api 文档都懒得写!程序员:“api工具惯的”_不吃西红柿丶的博客-CSDN博客 |
-
🍐 一、程序员为什么不爱写文档?是他们变懒了吗?
- 🍞 1. 客观 - 时间紧,任务重
- 🍆 2. 主观 - 缺乏经验,写作困难
- 🥕 3. 客观 - 需求变化快
- 🥔 二、写文档这么麻烦,那我们就不写了吗?
-
🍤 三、自动生成文档,解决一切烦恼
- 🍖 3.1 手动创建 API 文档
- 🍕 3.2 关联项目与 Swagger URL 自动创建文档
- 🌽 3.3 关联项目与代码仓库自动创建文档
- 🍎 3.4 基于IDEA插件,零注释生成文档
- 🍎 四、小编有话
🍐 一、程序员为什么不爱写文档?是他们变懒了吗?
关于大多数程序员不爱写文档问题, 我觉得可以从两个方面去拆解:主观原因、客观原因。
🍞 1. 客观 - 时间紧,任务重
需求方每次都是紧急需求,老板每次都要求敏捷开发,快速响应。
按时交付的压力已经让大多数程序员不堪重负,更别提写代码的同时同步维护文档了。而不写文档,或者糊弄文档又不影响开发进度。
🍆 2. 主观 - 缺乏经验,写作困难
正是由于长期不写文档或者随便一些,当需要去写的时候,发现无从下笔,写作可太难了!!!
而接口文档的要求相对来说较高,不仅需要内容详实,把问题讲清楚,还需要有清晰的层级结构,让其他读者快速获取到需要的信息,这对经常写代码缺乏文档经验的我们来说,本身也是一项挑战。(还记得写晋升答辩 PPT 的痛苦场面吧~ )
🥕 3. 客观 - 需求变化快
尤其是互联网公司,需求变化非常快,代码不停的迭代,文档来不及更新,和实际代码差异很大。天天加班做需求了,哪来的时间写文档。
当然,不写文档的问题也不能责怪程序员,更深层级的原因可能是公司流程、制度、管理等等方面的,这里就不展开说了,请各位领导不要对号入座。
🥔 二、写文档这么麻烦,那我们就不写了吗?
对于写文档这件事情来说,往往短期高估文档的重要性,长期低估文档的重要性。 短期以项目按时交付为主,项目细节也都还烂熟于心,但是长期来说,随着大脑的记忆内存被逐渐回收,当再次迭代之前的代码时,甚至有人员变更时,缺乏文档的部分往往成为黑盒子,与其花大量时间去探索解密别人的代码,还不如整体重构来得快!
于是,我们似乎陷入了工作永远做不完的怪圈:
🍤 三、自动生成文档,解决一切烦恼
针对文档管理的问题,Eolink 提供了完美的解决方案,满足了 Api 文档管理的 4 个强大能力。
-
根据代码生成文档
-
便捷的调试体验和自动生成测试数据
-
支持多场景分享文档
-
标准规范的 API 管理工具
同时,在 API 研发管理平台 中,也可以通过三种方式来一键创建 API 文档:
-
手动创建 API 文档
-
关联项目与代码仓库自动创建文档
-
关联项目与 Swagger URL 自动创建文档
🍖 3.1 手动创建 API 文档
API 研发管理平台提供了非常全面的 API 文档格式,能够详细记录您的 API 信息。这种方式适合所有用户,也是西红柿推荐的方式。
官网体验链接: 点我体验 Api 专业工具 !!!
操作方法: 登录 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 配置(其他代码仓库也支持,详见官网)
配置项 | 说明 |
---|---|
代码仓库类型 | 选择 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帐号,服务器填目标服务器域名。
-
如果使用的是SaaS,server后需要加上/api
-
如果使用的是私有云版本,需要在server后加上index.php
-
token目前使用的是个人帐号(邮箱/手机/帐号)
-
StringType决定出入参的字符串类型,只有参数名一开始就是遵守驼峰规范才会发现改变,预览窗口可看到变化结果
-
🍎 四、小编有话
强大的 Eolink,不仅帮我们解决了写文档,管理文档,迭代变更沟通协调等诸多问题。还有许许多多的惊喜,留给你自己探索吧!!
官网体验链接: 点我体验 Api 专业工具 !!!
最后,让我们大声喊出他的名字: 我要下班!文章来源:https://www.toymoban.com/news/detail-828595.html
不对,文档还没写完怎么下班,跟我重新喊:E O L I N K !!!文章来源地址https://www.toymoban.com/news/detail-828595.html
到了这里,关于现在的程序员真是越来越懒了,api 文档都懒得写!程序员:“api工具惯的”的文章就介绍完了。如果您还想了解更多内容,请在右上角搜索TOY模板网以前的文章或继续浏览下面的相关文章,希望大家以后多多支持TOY模板网!