關(guān)于大多數(shù)程序員不愛寫文檔問題， 我覺得可以從兩個方面去拆解：主觀原因、客觀原因。

1. 客觀 - 時間緊任務重，需求變化快

需求方每次都是緊急需求，老板每次都要求敏捷開發(fā)，快速響應。

按時交付的壓力已經(jīng)讓大多數(shù)程序員不堪重負，更別提寫代碼的同時同步維護文檔了。而不寫文檔，或者糊弄文檔又不影響開發(fā)進度。尤其是互聯(lián)網(wǎng)公司，需求變化非?？?，代碼不停的迭代，文檔來不及更新，和實際代碼差異很大。天天加班做需求了，哪來的時間寫文檔。

2. 主觀 - 缺乏經(jīng)驗，寫作困難

正是由于長期不寫文檔或者隨便一寫，當需要去寫的時候，發(fā)現(xiàn)無從下筆，寫作可太難了!!!

而接口文檔的要求相對來說較高，不僅需要內(nèi)容詳實，把問題講清楚，還需要有清晰的層級結(jié)構(gòu)，讓其他讀者快速獲取到需要的信息，這對經(jīng)常寫代碼缺乏文檔經(jīng)驗的我們來說，本身也是一項挑戰(zhàn)。還記得寫晉升答辯 PPT 的痛苦場面吧~

當然，不寫文檔的問題也不能責怪程序員，更深層級的原因可能是公司流程、制度、管理等等方面的，這里就不展開說了，請各位領(lǐng)導不要對號入座。

對于寫文檔這件事情來說，往往短期高估文檔的重要性，長期低估文檔的重要性。短期以項目按時交付為主，項目細節(jié)也都還爛熟于心，但是長期來說，隨著大腦的記憶內(nèi)存被逐漸回收，當再次迭代之前的代碼時，甚至有人員變更時，缺乏文檔的部分往往成為黑盒子，與其花大量時間去探索解密別人的代碼，還不如整體重構(gòu)來得快！

于是，我們似乎陷入了工作永遠做不完的怪圈：

針對文檔管理的問題，Eolink 提供了完美的解決方案，滿足了 Api 文檔管理的 4 個強大能力。

根據(jù)代碼生成文檔便捷的調(diào)試體驗和自動生成測試數(shù)據(jù)支持多場景分享文檔標準規(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 文檔格式，能夠詳細記錄您的 API 信息。這種方式適合所有用戶，也是我大力推薦的方式。

官網(wǎng)體驗鏈接：https://www.eolink.com/

操作方法：登錄 Eolink 后，在項目詳情頁點擊左側(cè) API 文檔功能，進入 API 管理頁面，點擊 添加 API，會進入 API 創(chuàng)建頁面。

私有云產(chǎn)品比線上 SaaS 產(chǎn)品支持更多的 API 協(xié)議，比如 TCP、UDP、SOAP、HSF 等。

API 編輯頁面中可以填寫 API 文檔、返回數(shù)據(jù)、額外說明等信息，您可以通過頂部的標簽切換。

3.2 關(guān)聯(lián)項目與 Swagger URL 自動創(chuàng)建文檔

API 研發(fā)管理平臺自動從該地址獲取最新 API 文檔。這種方式適合之前已經(jīng)在使用 Swagger，并且傾向于將文檔寫在代碼注解中的用戶。但這種方式會帶來代碼入侵的問題，讓代碼中加入了許多無關(guān)的信息從而增加維護成本。

操作方法：您可以給項目關(guān)聯(lián) Swagger 生成的 JSON 文件地址，API 研發(fā)管理平臺能夠遠程讀取 Swagger JSON 并自動生成 API 文檔。

進入 API 管理與測試，選擇項目，點擊左側(cè)欄的其他可以看到 API 文檔生成：

點擊添加來源，在彈窗中選擇通過 Swagger URL 生成 API 文檔，然后點擊下一步：

輸入 Swagger 生成的 JSON 地址，注意該 JSON 地址需要能夠通過網(wǎng)絡(luò)訪問，并且該地址返回的數(shù)據(jù)需要是 JSON 類型的數(shù)據(jù)，否則會提示無法訪問該地址。

配置完成后，界面會提示配置完成。此時您可以通過在當前頁面頁點擊 同步 按鈕，或者通過 Open API 觸發(fā)同步操作。

3.3 關(guān)聯(lián)項目與代碼倉庫自動創(chuàng)建文檔

API 研發(fā)管理平臺自動從代碼倉庫中掃描代碼注解生成 API 文檔。目前這種方式支持 Java 以及 PHP 兩種語言。這種方式也會帶來代碼入侵的問題。

可以給項目關(guān)聯(lián)代碼倉庫，API 研發(fā)管理平臺 能夠遠程讀取倉庫中的代碼注解并自動生成 API 文檔，能夠識別 Swagger 2.0、OpenAPI 3.0 的代碼注解格式。當然，為了標準化管理，新的規(guī)范都用 OpenAPI 3.0 了。

看起來，目前支持的倉庫類型有：Github、Gitlab、碼云等等。

操作方法：進入項目頁，點擊其他，再點擊 API 文檔生成添加來源 ，在彈窗中設(shè)置需要掃碼的代碼倉庫，點擊立即同步即可。

GitHub 配置（其他代碼倉庫也支持，詳見官網(wǎng)）

3.4 基于IDEA插件，零注釋生成文檔

更加牛逼的自動化生成方式是：“基于IDEA插件零注釋生成文檔”。

零注釋生成文檔，安裝和配置方法：

在IDEA插件市場中搜索“apikit”，找到“Eolink ApiKit”插件安裝即可。目前僅支持2020.03-2022.03版本的IDEA首次上傳需要填寫配置信息，配置信息項目之間獨立配置信息獲取途徑：SpaceKey和ProjectHashKey通過Eolink的web版url中的參數(shù)獲取，token填自己Eolink帳號，服務器填目標服務器域名。如果使用的是SaaS，server后需要加上/api如果使用的是私有云版本，需要在server后加上index.phptoken目前使用的是個人帳號（郵箱/手機/帳號）StringType決定出入?yún)⒌淖址愋?，只有參?shù)名一開始就是遵守駝峰規(guī)范才會發(fā)現(xiàn)改變，預覽窗口可看到變化結(jié)果

強大的 Eolink，不僅幫我們解決了寫文檔，管理文檔，迭代變更溝通協(xié)調(diào)等諸多問題。還有許許多多的驚喜，留給你自己探索吧??！