现在的程序员真是越来越懒了,api 文档都懒得写!程序员:“api工具惯的”

Posted 不吃西红柿丶

tags:

篇首语:本文由小常识网(cha138.com)小编为大家整理,主要介绍了现在的程序员真是越来越懒了,api 文档都懒得写!程序员:“api工具惯的”相关的知识,希望对你有一定的参考价值。

为了让大家更能清楚了解 Api 相关往期内容,我写了一个阅读指引:

序号学习路径指引链接
1Api -- 连接世界的 Super StarApi -- 连接世界的Super Star_不吃西红柿丶的博客-CSDN博客
2软件吞噬世界,Api 快速入门到放弃软件吞噬世界,Api快速入门到放弃_不吃西红柿丶的博客-CSDN博客
3Apifox vs Eolink,国内 Api 工具哪家强?Apifox vs Eolink,国内 Api 工具哪家强?_不吃西红柿丶的博客-CSDN博客
4都 2203 年了,还有人使用 word 调试 Api !!!活久见:都 2203 年了,你还在使用 word 调试 API_不吃西红柿丶的博客-CSDN博客
5现在的程序员真是越来越懒了,api 文档都懒得写!程序员:“api工具惯的”现在的程序员真是越来越懒了,api 文档都懒得写!程序员:“api工具惯的”_不吃西红柿丶的博客-CSDN博客

🍐 一、程序员为什么不爱写文档?是他们变懒了吗?

关于大多数程序员不爱写文档问题, 我觉得可以从两个方面去拆解:主观原因、客观原因。

🍞 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插件零注释生成文档”。

零注释生成文档,安装和配置方法:

  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,不仅帮我们解决了写文档,管理文档,迭代变更沟通协调等诸多问题。还有许许多多的惊喜,留给你自己探索吧!!

官网体验链接: 点我体验 Api 专业工具 !!! 

最后,让我们大声喊出他的名字: 我要下班!

不对,文档还没写完怎么下班,跟我重新喊:E O L I N K !!!

以上是关于现在的程序员真是越来越懒了,api 文档都懒得写!程序员:“api工具惯的”的主要内容,如果未能解决你的问题,请参考以下文章

现在的程序员真是越来越懒了,api 文档都懒得写!程序员:“api工具惯的”

我最近在用的一款神器,功能多到炸!

深入理解java 注解(Annotation)重版

微信小程序支付

看看人家,那后端API接口写得,那叫一个优雅!

ShowDoc上手构建api文档