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

这篇具有很好参考价值的文章主要介绍了现在的程序员真是越来越懒了,api 文档都懒得写!程序员:“api工具惯的”。希望对大家有所帮助。如果存在错误或未考虑完全的地方,请大家不吝赐教,您也可以点击"举报违法"按钮提交疑问。

为了让大家更能清楚了解 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. 客观 - 时间紧,任务重

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

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

懒得自己写代码,科技情报站,java,intellij-idea,开发语言

🍆 2. 主观 - 缺乏经验,写作困难

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

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

🥕 3. 客观 - 需求变化快

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

懒得自己写代码,科技情报站,java,intellij-idea,开发语言

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

🥔 二、写文档这么麻烦,那我们就不写了吗?

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

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

懒得自己写代码,科技情报站,java,intellij-idea,开发语言

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

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

  • 根据代码生成文档

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

  • 支持多场景分享文档

  • 标准规范的 API 管理工具

懒得自己写代码,科技情报站,java,intellij-idea,开发语言

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

  • 手动创建 API 文档

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

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

🍖 3.1 手动创建 API 文档

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

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

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

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

懒得自己写代码,科技情报站,java,intellij-idea,开发语言

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

懒得自己写代码,科技情报站,java,intellij-idea,开发语言

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

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

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

懒得自己写代码,科技情报站,java,intellij-idea,开发语言

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

懒得自己写代码,科技情报站,java,intellij-idea,开发语言

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

懒得自己写代码,科技情报站,java,intellij-idea,开发语言

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

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

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

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

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

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

懒得自己写代码,科技情报站,java,intellij-idea,开发语言

GitHub 配置(其他代码仓库也支持,详见官网)

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

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

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

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

懒得自己写代码,科技情报站,java,intellij-idea,开发语言

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

懒得自己写代码,科技情报站,java,intellij-idea,开发语言

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

不对,文档还没写完怎么下班,跟我重新喊:E O L I N K !!!文章来源地址https://www.toymoban.com/news/detail-828595.html

到了这里,关于现在的程序员真是越来越懒了,api 文档都懒得写!程序员:“api工具惯的”的文章就介绍完了。如果您还想了解更多内容,请在右上角搜索TOY模板网以前的文章或继续浏览下面的相关文章,希望大家以后多多支持TOY模板网!

本文来自互联网用户投稿,该文观点仅代表作者本人,不代表本站立场。本站仅提供信息存储空间服务,不拥有所有权,不承担相关法律责任。如若转载,请注明出处: 如若内容造成侵权/违法违规/事实不符,请点击违法举报进行投诉反馈,一经查实,立即删除!

领支付宝红包 赞助服务器费用

相关文章

  • 什么是云仓?为什么现在越来越多电商商家合作云仓?

    随着物流行业的发展,相信越来越多的人逐渐了解云仓行业是什么,也许很多人会问:云仓一对一发货是一种什么样的模式?这个问题想必之前在其他文章里看过,所以今天在这里详细说一下一代云仓。 简单来说,云仓一对一配送是一家第三方仓储公司,根据自身优势,为电

    2024年02月11日
    浏览(52)
  • 阿里云让我越来越反感

    跟阿里云接触由8,9年的时间了,算起来是一个忠实的阿里云用户呢,因为我带团队比较早,所以基本上只要是我的团队,我都会选择阿里云的产品作为我的技术方案。但是最近2年,我对阿里云的印象是越来越差了。 先说说背景把,我带了个50来人的技术团队,因为公司的发

    2024年02月07日
    浏览(53)
  • 越来越“变态”的验证码,到底在验证什么?

    验证码要验证的是它所面对的是真实的人还是计算机程序。最开始的验证码非常的简单,只要输入几个数字就可以。不知道从何时开始见证了变得越来越变态,变得花样不断的验证,验证码就不仅仅是视力的挑战了,有的时候已经是视力及智力的双重挑战。 还有大家经常看到

    2024年02月11日
    浏览(43)
  • Edge浏览器越来越难用了?又惹“众怒”!

    最近,Edge浏览器进行正式开始推送v111稳定版更新,这可把我们很多企业用户恶心坏了。 该版本在界面通过右上角,添加了我们一个企业非常没有突兀碍眼、不协调的Bing按钮。 更糟糕的是,微软没有提供隐藏选项,所以你不能只是移除禁用。 对于一个集成的这个必应聊天,

    2024年02月05日
    浏览(50)
  • 为什么越来越多的企业选择云计算?

    1.当下企业信息化的痛点 企业信息化,这也算是一个老生常谈的话题了,整个中国业内前前后后应该喊了有十多年了。不过到目前为止,我国很多企业公司都还没真正形成一个完整的信息化框架,或者只是运用了一个简单财务或客户管理系统。甚至还有很多公司企业根本连基

    2024年02月04日
    浏览(49)
  • 为什么越来越多的企业选择云计算

    目录 一、前言 二、云计算的基础概念 2.1 云计算的定义 2.2 云计算的发展历程 2.3 云计算的基本架构 三、 企业采用云计算的优势 四、 行业应用案例 五、未来发展与挑战 六、总结 随着数字化转型的加速,越来越多的企业开始选择云计算作为信息技术应用的基础设施。那么,

    2024年02月02日
    浏览(63)
  • IPV6使用越来越广,您会配置吗?

    前面针对IPv6写过一篇文章,但是好多网友反映没有读懂,今天再给大家把内容浓缩一下,教给大家如何配置。 IPV6的推出主要是为了解决地址空间的不足,从而进一步的促进互联网的发展。IPV6地址空间大到惊人,有人比喻地球上的每粒沙子都可以拥有一个IPv6地址。   128bit的

    2024年02月13日
    浏览(52)
  • 越来越看不懂的企业数字化转型……

    近日和一做乙方的老友相聚谈起了今年的企业数字化转型情况,都有一个整体的感受那就是: 越来越看不懂了,有价无市,看似热闹,实则观望。   经历几年疫情,行业内都普遍认为企业领导对于数字化的重视程度在提高,毕竟数字化的技术能力及所取得的成果在这两年是

    2024年02月13日
    浏览(55)
  • mac电脑储存内存越来越小如何清理释放空间?

    如果你是一位Mac系统的用户,可能会发现你的电脑储存空间越来越小。虽然Mac系统设计得非常优秀,但是系统数据和垃圾文件也会占据大量的储存空间。在这篇文章中,我们将探讨mac系统数据怎么这么大,以及mac清理系统数据怎么清理。 一、mac系统数据怎么这么大 许多Mac用

    2024年02月08日
    浏览(61)
  • 加密越来越简单——用JavaScript实现数据加密和解密

    在当今互联网的世界中,安全性越来越受到关注,数据加密成为了必不可少的一环。Javascript作为前端开发的主要语言之一,也有着重要的加密应用。本篇博客将讨论Javascript加密的概念、常用算法以及代码示例。 Javascript加密 ,简单来说就是通过Javascript实现数据的加密和解密

    2024年02月15日
    浏览(64)

觉得文章有用就打赏一下文章作者

支付宝扫一扫打赏

博客赞助

微信扫一扫打赏

请作者喝杯咖啡吧~博客赞助

支付宝扫一扫领取红包,优惠每天领

二维码1

领取红包

二维码2

领红包