專業的yapi不用，你用showdoc？用showdoc還不如自己寫一個，markdown/editor/md2html有合適解決方案寫一個文件管理不就像寫個demo一樣麼？

我覺得，要看你的實際出發點，要解決什麼問題。不是像其他說的，用就用好的。我們要合適的。

這類的工具有很多。比如apidoc,showdoc,apizza,rap2等

1.假如你只是歸檔及前段看的話。showdoc就可以，內網路都可以，使用簡單（我用的就是這個）。 apidoc也可以（複雜些）

2假如你還要更復雜的功能，你就要選相對專業些的工具了。比如你說的yapi

推薦YApi做介面管理平臺！

下面說說為什麼要用YApi做介面管理平臺。

隨著 Web 技術的發展，前後端分離構架變的越來越流行。前後端分離使後端專注於資料處理和定義前端所需要的介面，前端負責資料的展現和互動，大大細化了開發者的職責，提高了開發效率，但與此同時也帶來了一些問題：

對於前端工程師，後端提供的介面文件，大多是不規範的，有使用 wiki 的，有 word 文件的，甚至還有用即時聊天軟體溝通的，後端介面對於前端就像一個黑盒子，經常遇到問題是介面因未知原因增加引數了，引數名變了，引數被刪除了。對於後端工程師，介面對接時總是需要寫冗雜繁瑣的文件，需要大量時間去維護介面文件。

前端開發的功能在後端功能還沒完成前，因為前端的功能依賴於後端的資料，導致工作無法順利展開。為了解決這個問題，有些前端工程師在程式碼注入 json，還有後端工程師臨時搭建一套測試資料伺服器，這種情況下勢必會影響工作效率和程式碼質量，也不能及時進行欄位的更新。

介面資料正確性無法得到保證。前端呼叫後端的介面資料渲染到 檢視，資料一旦出錯，將會導致檢視和互動也出現問題，保證後端介面資料正確性變的愈來愈重要。介面自動化測試就是用來解決這個問題，但傳統的介面測試框架使用成本很高，很多團隊採用肉眼比對方式，效率很低。

Nei 是網易前端事業部的產品，在這些產品中算是做得比較好的， nei 是專注做 saas 服務這塊，沒有開源版本。對於去哪兒內部，肯定不會把公司機密的介面資料放到第三方平臺。

Rap 是阿里媽媽 MUX 團隊2013年出的一款產品，從時間上看是同類產品中最早的。Rap 是後端工程師基於 java 開發的，如果想定製部分功能，還需要學習 java，而我們部門大家對 java 都不熟悉。另一方面 Rap 沒有介面測試功能，而後端使用其他工具（postman， restlet）測試介面，將導致不能及時更新介面文件。

Easy-mock 是大搜車無線團隊出的一款產品，Easy-mock 定位是介面資料的模擬，解決前端依賴後端介面資料的問題，在同類產品中 mock 服務做得比較好。Easy-mock 專注於前端資料的模擬，但無法解決去哪兒現有的問題。

Nei，Rap 介面管理平臺共同存在的問題是不易維護介面返回資料。筆者曾跟一個使用過 Rap 的後端工程師聊過，他說每次定義後端介面返回資料欄位，好幾個百個欄位需要更新很長時間。Nei，Rap 是基於維護一個 json-schema 方式定義後端返回資料結構，我們假設某個介面有100個欄位，如果基於 json-shema 那麼就要維護差不多 600 多左右欄位的更新。這麼大工作量的，很可能導致後端工程師根本沒有動力去維護。

比較遺憾的是，這幾款優秀的產品，都缺失了一些我們在意的關鍵特徵。我們可能需要做比較大的改動才能夠基本滿足自己的需求，這個工作量很有可能會超過重新開發一次。所以我們開始自主研發一個全新的介面管理平臺，我們希望它能夠提供介面文件管理，介面資料模擬（Mock），介面除錯，自動化測試等功能，讓前後端介面相關的工作進行的更加高效。這就是 YApi 介面管理平臺斐然由來，下面簡要聊聊 YApi 是如何實現上述這些特徵的。

1. 共同維護一份介面定義，連線前後端

大家看下圖，在後端開發介面過程中，介面開發和測試介面這是必不可少的環節，但文件因為沒有跟介面開發和測試聯絡到一起，被孤立。後端要維護對於他們冗雜繁瑣的文件，是件收益很低的事情。沒有人喜歡做收益低的事情，所以最終的解決辦法就是要提高收益。下面詳細說明解決方案。

在介面開發過程中，後端通常都會使用 postman 等類似的工具測試介面，而測試介面是在開發過程中一個必要的過程。假如引數有改動，大家肯定會在 postman 等工具上更新欄位和測試介面。由此可以聯想到，

如果能有一款工具既可用來做測試介面，又能作為介面文件工具，將介面文件和介面測試連線到一起，不就解決了此問題。YApi 解決方案是將介面文件和測試透過單一資料來源連線到一起，如果有改動，因為改的是單一的資料來源，就不會出現更新滯後和不及時問題。

2. 前端 Mock Server 方案

資料 Mock 服務在開發前期是非常頭疼的一個問題。大多數情況下，介面請求引數和返回資料都是後端規定的，在後端介面沒有完成之前，介面對於前端就是一個黑洞，可能最初對介面的定義跟實際後端做出的介面會有非常大的不同。這個時候就需要有一個工具，不僅能模擬真實介面的情況，還能關聯介面文件，在後端開發過程中，可以隨時調整介面定義，並通知給前端開發者改動資訊。

在 YApi 平臺，前後端只要維護介面定義的響應資料，就可以生成需要的模擬資料，下面這段程式碼定義了生成資料模板：

可生成如下的模擬資料：

以往的資料 mock 方案難免會影響專案原始碼，yapi 使用了伺服器代理的方案，只需要在你的開發機做下伺服器反向代理配置，不用修改專案一行原始碼，即可獲取到所有的 mock 資料。

基礎的 Mock 工具已經能滿足大部分的需求了，但有些複雜場景是無法實現的。例如：當我做一個數據列表頁面，需要測試某個欄位在各種長度下的 ui 表現，還有當資料為空時的 ui 表現。YApi 提供了期望和自定義指令碼的功能。

本文主要介紹自定義指令碼功能，期望功能可參考 yapi 平臺文件。

自定義指令碼可根據請求的引數，cookie 資訊，使用 js 指令碼自定義返回的資料。我們假設有個場景，我希望透過 cookie "_type" 控制列表頁面資料顯示，假設 _type 是 error，那麼列表顯示異常錯誤資訊；假設 _type 是 empty ，列表顯示為空。可使用下面程式碼實現：

3.自動化測試

介面開發完成後，後續的迭代是非常多的，每次對原始碼的修改，都需要大量的測試才能確保介面是否正確。人工判斷肯定是不好的，最好的辦法是做成自動化，但自動化測試又是一件成本非常高的事情，需要後端人員和QA人員學習相關的框架，和寫大量的程式碼。YApi 簡化了這一個過程，基於一個視覺化介面，就算不懂程式開發，只需配置相關的引數和斷言語句，就能實現自動化測試，非常的易用。

除了基本的功能外，YApi 還提供了強大的 pre-script 和視覺化表示式功能，pre-script 包括請求引數處理指令碼和響應資料處理指令碼兩部分。透過自定義 js 指令碼方式改變請求的引數和返回的 response 資料。他的使用場景如下：

介面請求引數需要加密及返回 response 解密

介面請求引數需要新增計算 token

視覺化表達主要是為了方便使用者生成自動化測試所用到的引數，透過一個樹形選擇性，快速引用所依賴的引數值。

4.外掛機制

YApi 最強大的一點莫過於他的外掛機制，我們去哪兒各個業務線有不同的需求，透過 YApi 預留的鉤子，開發不同的外掛解決，比如我們現有的 qsso 登入，swagger 資料匯入就是透過外掛機制實現的，我們團隊最近還在跟業務部門討論使用外掛實現壓力測試功能等。總得來說，YApi基於外掛機制，既滿足了產品需求的多樣性，又保證了核心足夠易用和簡潔。

5. 開源和易部署

為了幫助更多開發者和提升大家的工作效率，YApi 不僅開源到 github，還提供了一個 cli 工具方便廣大開發者部署。使用 yapi-cli 提供的視覺化部署方案，即便你不懂任何 nodejs、mongodb 的知識，也能輕鬆一鍵部署。

YApi 已在去哪兒大面積使用，對 200+ 專案介面進行管理，每週有上萬次 mock 請求。在開源以後，越來越多的公司和團隊使用 YApi， github star 數已經上升到 1.1k了。YApi 在未來還將繼續專注於介面管理方面的功能，讓 YApi 成為各位開發者的好幫手。

demo 站點：yapi.demo.qunar.com

github: github.com/ymfe/yapi

推薦YAPI,我們一直在用。支援mock,請求跟蹤，可以劃分許可權，介面變動可以傳送通知給相關人員。最重要的是開源 可以私網部署