為了讓大家更能清楚了解 Api 相關(guān)往期內(nèi)容，我寫了一個閱讀指引：
| 序號 | 學(xué)習(xí)路徑指引 | 鏈接 |
|---|---|---|
| 1 | Api -- 連接世界的 Super Star | Api -- 連接世界的Super Star_不吃西紅柿丶的博客-CSDN博客 |
| 2 | 軟件吞噬世界，Api 快速入門到放棄 | 軟件吞噬世界，Api快速入門到放棄_不吃西紅柿丶的博客-CSDN博客 |
| 3 | Apifox vs Eolink，國內(nèi) Api 工具哪家強(qiáng)？ | Apifox vs Eolink，國內(nèi) Api 工具哪家強(qiáng)？_不吃西紅柿丶的博客-CSDN博客 |
| 4 | 都 2203 年了，還有人使用 word 調(diào)試 Api !!! | 活久見：都 2203 年了，你還在使用 word 調(diào)試 API_不吃西紅柿丶的博客-CSDN博客 |
| 5 | 現(xiàn)在的程序員真是越來越懶了，api 文檔都懶得寫！程序員：“api工具慣的” | 現(xiàn)在的程序員真是越來越懶了，api 文檔都懶得寫！程序員：“api工具慣的”_不吃西紅柿丶的博客-CSDN博客 |
-
?? 一、程序員為什么不愛寫文檔？是他們變懶了嗎？
- ?? 1. 客觀 - 時間緊，任務(wù)重
- ?? 2. 主觀 - 缺乏經(jīng)驗，寫作困難
- ?? 3. 客觀 - 需求變化快
- ?? 二、寫文檔這么麻煩，那我們就不寫了嗎？
-
?? 三、自動生成文檔，解決一切煩惱
- ?? 3.1 手動創(chuàng)建 API 文檔
- ?? 3.2 關(guān)聯(lián)項目與 Swagger URL 自動創(chuàng)建文檔
- ?? 3.3 關(guān)聯(lián)項目與代碼倉庫自動創(chuàng)建文檔
- ?? 3.4 基于IDEA插件，零注釋生成文檔
- ?? 四、小編有話
?? 一、程序員為什么不愛寫文檔？是他們變懶了嗎？
關(guān)于大多數(shù)程序員不愛寫文檔問題， 我覺得可以從兩個方面去拆解：主觀原因、客觀原因。
?? 1. 客觀 - 時間緊，任務(wù)重
需求方每次都是緊急需求，老板每次都要求敏捷開發(fā)，快速響應(yīng)。
按時交付的壓力已經(jīng)讓大多數(shù)程序員不堪重負(fù)，更別提寫代碼的同時同步維護(hù)文檔了。而不寫文檔，或者糊弄文檔又不影響開發(fā)進(jìn)度。
?? 2. 主觀 - 缺乏經(jīng)驗，寫作困難
正是由于長期不寫文檔或者隨便一些，當(dāng)需要去寫的時候，發(fā)現(xiàn)無從下筆，寫作可太難了!!!
而接口文檔的要求相對來說較高，不僅需要內(nèi)容詳實，把問題講清楚，還需要有清晰的層級結(jié)構(gòu)，讓其他讀者快速獲取到需要的信息，這對經(jīng)常寫代碼缺乏文檔經(jīng)驗的我們來說，本身也是一項挑戰(zhàn)。（還記得寫晉升答辯 PPT 的痛苦場面吧~ ）
?? 3. 客觀 - 需求變化快
尤其是互聯(lián)網(wǎng)公司，需求變化非常快，代碼不停的迭代，文檔來不及更新，和實際代碼差異很大。天天加班做需求了，哪來的時間寫文檔。
當(dāng)然，不寫文檔的問題也不能責(zé)怪程序員，更深層級的原因可能是公司流程、制度、管理等等方面的，這里就不展開說了，請各位領(lǐng)導(dǎo)不要對號入座。
?? 二、寫文檔這么麻煩，那我們就不寫了嗎？
對于寫文檔這件事情來說，往往短期高估文檔的重要性，長期低估文檔的重要性。 短期以項目按時交付為主，項目細(xì)節(jié)也都還爛熟于心，但是長期來說，隨著大腦的記憶內(nèi)存被逐漸回收，當(dāng)再次迭代之前的代碼時，甚至有人員變更時，缺乏文檔的部分往往成為黑盒子，與其花大量時間去探索解密別人的代碼，還不如整體重構(gòu)來得快！
于是，我們似乎陷入了工作永遠(yuǎn)做不完的怪圈：
?? 三、自動生成文檔，解決一切煩惱
針對文檔管理的問題，Eolink 提供了完美的解決方案，滿足了 Api 文檔管理的 4 個強(qiáng)大能力。
-
根據(jù)代碼生成文檔
-
便捷的調(diào)試體驗和自動生成測試數(shù)據(jù)
-
支持多場景分享文檔
-
標(biāo)準(zhǔn)規(guī)范的 API 管理工具
同時，在 API 研發(fā)管理平臺 中，也可以通過三種方式來一鍵創(chuàng)建 API 文檔：
-
手動創(chuàng)建 API 文檔
-
關(guān)聯(lián)項目與代碼倉庫自動創(chuàng)建文檔
-
關(guān)聯(lián)項目與 Swagger URL 自動創(chuàng)建文檔
?? 3.1 手動創(chuàng)建 API 文檔
API 研發(fā)管理平臺提供了非常全面的 API 文檔格式，能夠詳細(xì)記錄您的 API 信息。這種方式適合所有用戶，也是西紅柿推薦的方式。
官網(wǎng)體驗鏈接： 點(diǎn)我體驗 Api 專業(yè)工具 !!!?
操作方法： 登錄 Eolink 后，在項目詳情頁點(diǎn)擊左側(cè) API 文檔功能，進(jìn)入 API 管理頁面，點(diǎn)擊 添加 API，會進(jìn)入 API 創(chuàng)建頁面。
私有云產(chǎn)品比線上 SaaS 產(chǎn)品支持更多的 API 協(xié)議，比如 TCP、UDP、SOAP、HSF 等。
API 編輯頁面中可以填寫 API 文檔、返回數(shù)據(jù)、額外說明等信息，您可以通過頂部的標(biāo)簽切換。
?? 3.2 關(guān)聯(lián)項目與 Swagger URL 自動創(chuàng)建文檔
API 研發(fā)管理平臺自動從該地址獲取最新 API 文檔。這種方式適合之前已經(jīng)在使用 Swagger，并且傾向于將文檔寫在代碼注解中的用戶。但這種方式會帶來代碼入侵的問題，讓代碼中加入了許多無關(guān)的信息從而增加維護(hù)成本。
操作方法： 您可以給項目關(guān)聯(lián) Swagger 生成的 JSON 文件地址，API 研發(fā)管理平臺能夠遠(yuǎn)程讀取 Swagger JSON 并自動生成 API 文檔。
進(jìn)入 API 管理與測試，選擇項目，點(diǎn)擊左側(cè)欄的其他可以看到 API 文檔生成
點(diǎn)擊添加來源，在彈窗中選擇通過 Swagger URL 生成 API 文檔，然后點(diǎn)擊下一步：
輸入 Swagger 生成的 JSON 地址，注意該 JSON 地址需要能夠通過網(wǎng)絡(luò)訪問，并且該地址返回的數(shù)據(jù)需要是 JSON 類型的數(shù)據(jù)，否則會提示無法訪問該地址。
配置完成后，界面會提示配置完成。此時您可以通過在當(dāng)前頁面頁點(diǎn)擊 同步 按鈕，或者通過 Open API 觸發(fā)同步操作。
?? 3.3 關(guān)聯(lián)項目與代碼倉庫自動創(chuàng)建文檔
API 研發(fā)管理平臺自動從代碼倉庫中掃描代碼注解生成 API 文檔。目前這種方式支持 Java 以及 PHP 兩種語言。這種方式也會帶來代碼入侵的問題。
可以給項目關(guān)聯(lián)代碼倉庫，API 研發(fā)管理平臺 能夠遠(yuǎn)程讀取倉庫中的代碼注解并自動生成 API 文檔，能夠識別 Swagger 2.0、OpenAPI 3.0 的代碼注解格式。當(dāng)然，為了標(biāo)準(zhǔn)化管理，新的規(guī)范都用 OpenAPI 3.0 了。
看起來，目前支持的倉庫類型有：Github、Gitlab、碼云等等。
操作方法： 進(jìn)入項目頁，點(diǎn)擊其他，再點(diǎn)擊 API 文檔生成添加來源 ，在彈窗中設(shè)置需要掃碼的代碼倉庫，點(diǎn)擊立即同步即可。
GitHub 配置（其他代碼倉庫也支持，詳見官網(wǎng)）
| 配置項 | 說明 |
|---|---|
| 代碼倉庫類型 | 選擇 Github |
| 代碼倉庫地址 | 默認(rèn)填寫 Github 官網(wǎng) |
| 用戶名 | Github 賬戶名稱 |
| 倉庫名 | Github Repository 倉庫名稱 |
| 訪問私鑰 | 倉庫私人令牌在 GitHub Repository 的 Settings->Developer settings->Personal access tokens 中生成 |
| 需要掃描的分支 | 默認(rèn)為 master 分支，您也可以選擇實際需要掃描的代碼分支 |
| 需要掃描的 API 目錄路徑 | API 層相關(guān)代碼的存放路徑 |
| 需要掃描的數(shù)據(jù)結(jié)構(gòu)目錄路徑 | 數(shù)據(jù)結(jié)構(gòu)相關(guān)配置信息的存放路徑 |
?? 3.4 基于IDEA插件，零注釋生成文檔
更加牛逼的自動化生成方式是：“基于IDEA插件零注釋生成文檔”。
零注釋生成文檔，安裝和配置方法：
-
在IDEA插件市場中搜索“apikit”，找到“Eolink ApiKit”插件安裝即可。
-
目前僅支持2020.03-2022.03版本的IDEA
-
首次上傳需要填寫配置信息，配置信息項目之間獨(dú)立
- 配置信息獲取途徑：SpaceKey和ProjectHashKey通過Eolink的web版url中的參數(shù)獲取，token填自己Eolink帳號，服務(wù)器填目標(biāo)服務(wù)器域名。
-
如果使用的是SaaS，server后需要加上/api
-
如果使用的是私有云版本，需要在server后加上index.php
-
token目前使用的是個人帳號（郵箱/手機(jī)/帳號）
-
StringType決定出入?yún)⒌淖址愋?，只有參?shù)名一開始就是遵守駝峰規(guī)范才會發(fā)現(xiàn)改變，預(yù)覽窗口可看到變化結(jié)果
-
?? 四、小編有話
強(qiáng)大的 Eolink，不僅幫我們解決了寫文檔，管理文檔，迭代變更溝通協(xié)調(diào)等諸多問題。還有許許多多的驚喜，留給你自己探索吧??！
官網(wǎng)體驗鏈接： 點(diǎn)我體驗 Api 專業(yè)工具 !!!?
最后，讓我們大聲喊出他的名字： 我要下班！文章來源：http://www.zghlxwxcb.cn/news/detail-828595.html
不對，文檔還沒寫完怎么下班，跟我重新喊：E O L I N K !!!文章來源地址http://www.zghlxwxcb.cn/news/detail-828595.html
到了這里，關(guān)于現(xiàn)在的程序員真是越來越懶了，api 文檔都懶得寫！程序員：“api工具慣的”的文章就介紹完了。如果您還想了解更多內(nèi)容，請在右上角搜索TOY模板網(wǎng)以前的文章或繼續(xù)瀏覽下面的相關(guān)文章，希望大家以后多多支持TOY模板網(wǎng)！
