推薦一款 自動生成文檔的IDEA 牛x插件！
每個開發(fā)都不想寫文檔。當(dāng)你不想寫接口文檔時，可以通過安裝插件在 IDEA 里實現(xiàn)自動同步，一邊寫代碼一邊同步接口文檔給你的前端、測試同學(xué)。以下內(nèi)容手把手教你怎么操作（這里僅面向使用 IDEA 編輯器、遵循 Java Spring 框架注釋規(guī)范的同學(xué)）：
首先，你需要安裝一個插件
IDEA 插件市場里搜索 「Apifox Helper」，這是國內(nèi)一個做 API 協(xié)作管理平臺的廠商（Apifox）做的插件，可以非常方便自動生成接口文檔并且同步到你的項目中。這個插件可以實現(xiàn)代碼零入侵自動生產(chǎn)接口文檔。
IDEA 安裝插件：打開 IDEA > Preferences(Settings) > Plugins，搜索 Apifox Helper，點擊安裝。這里如果存在安裝速度慢，你也可以去 Jetbrains Marketplace 的官網(wǎng)下載。
安裝完成后，你可以選擇同步到 Apifox 項目中，也可以直接導(dǎo)出 markdown 文檔。如果是同步到 Apifox 項目，你還需要下載或注冊 Apifox 軟件，創(chuàng)建一個對應(yīng)的項目：
注冊/下載地址：http://apifox.cn/b3zmays1 ，直接微信掃一掃就可以，非常簡單。
創(chuàng)建項目：點擊創(chuàng)建團(tuán)隊 >新建項目，填入對應(yīng)的項目名稱。
（這里強烈推薦同步到 Apifox 項目，原因后面說）
第二步，把你 IDEA 中的項目和 Apifox 的項目關(guān)聯(lián)
插件安裝成功后，要將 IDEA 內(nèi)的項目與 Apifox 的項目進(jìn)行相關(guān)聯(lián)，需要配置令牌。在 IDEA 中進(jìn)入插件設(shè)置界面 Preferences(Settings) > Apifox Helper 中填寫即可。需要填寫的基礎(chǔ)信息有三個：
Apifox 服務(wù)器地址：?默認(rèn) Apifox API 服務(wù)地址為 https://api.apifox.cn，默認(rèn)就填好了，不需要修改。
填寫?Apifox 個人訪問令牌：?在 Apifox 個人頭像處的【賬號設(shè)置】中選擇【API 訪問令牌】，新建令牌后復(fù)制生成的 Token 填寫到以上插件設(shè)置中。
模塊項目 ID 配置：?這項主要是進(jìn)行代碼模塊名和項目 ID 的映射關(guān)系配置，在 Apifox 中對應(yīng)項目的【項目設(shè)置】中選擇【基本設(shè)置】，復(fù)制并保存項目 ID，填寫在以上的對應(yīng)模塊名處。
到這里，就完成全部的設(shè)置動作，可以實現(xiàn)文檔的自動生成和更新同步了。說明一下：每個項目只需要開始的時候設(shè)置這一次，后面就不需要做這個操作了。
第三步，自動生成接口文檔
打開需要上傳的 Controller 文件，右鍵選擇「 Upload to Apifox」。
去 Apifox 項目內(nèi)，就可以看到剛才自動同步過來的文檔了。
當(dāng)后續(xù)接口代碼有變動或更新時，再次點擊「 Upload to Apifox」就可以同步。
為什么推薦創(chuàng)建一個 Apifox 項目？
這個插件雖然支持導(dǎo)出 markdown，但給別人分享分檔的時候不是很方便，有更新的時候也不會同步，需要反復(fù)導(dǎo)出。使用 Apifox 項目就可以直接給別人分享一個鏈接就可以，你之后接口的更新也會直接同步，對方看到的永遠(yuǎn)是最新的。另外，Apifox 這個產(chǎn)品本身還有很豐富的 API 調(diào)試、Mock 、自動化測試等功能，你的前端和測試也可以直接在上面做后續(xù)的工作了。這里不細(xì)說，有興趣的可以去找他們官方文檔了解。
有了這個插件，你還可以直接在 IDEA 里調(diào)試
Apifox Helper 支持在 IDEA 中一鍵發(fā)起接口自測，不需要切換其他軟件。在 IDEA 中選中需要調(diào)試的 API 文件，右鍵選擇「Call API」發(fā)起請求就可以。
當(dāng)然，以上只是簡單版本的自動同步文檔，沒有什么特殊情況也就可以滿足使用了。當(dāng)然，可能會存在一些特殊的要求，比如說，設(shè)置接口 API 所在的文件夾名稱、想要忽略某些 API 不同步等等情況。在他們的官方文檔上是推薦使用配置文件的方式實現(xiàn)你各種特殊規(guī)則和要求的。詳情可以自行去 Apifox 官方查閱。
和 Swagger 有啥不一樣？
很多開發(fā)都習(xí)慣用 Swagger，用 Swagger 可以一定程度上解決自動生成文檔的問題，但有一個很大的缺點：你需要寫大量的注釋，會對你的邏輯代碼有入侵。并且在功能的全面性上不如 Apifox 。
Swagger：需要寫注釋，對邏輯代碼有入侵，功能單一；
Apifox：可以基本實現(xiàn)代碼零入侵，使用標(biāo)準(zhǔn)的 Javadoc 注釋就可以自動生成。同時它也支持同步 Swagger 的文檔到項目里。還有 API Mock、自動化測試等延伸功能。
推薦用法是可以省略 Swagger 這一步，直接安裝這個插件使用就可以。
