在日常開發中，最容易被吐槽的就是程式碼寫的爛，沒有註釋鬼知道你這個是什麼意思啊？

另一個就是文件不齊全，這些介面是幹嘛的？引數是什麼意思？等等問題。

歸根到底還是沒有嚴格的開發規範，最重要的還是要有方便的工具來幫助我們落地這些規範。

今天給大家推薦一個開源的 API 管理工具，如果還沒有用上的感覺看看吧。

YAPI

YApi 是高效、易用、功能強大的 api 管理平臺，旨在為開發、產品、測試人員提供更優雅的介面管理服務。可以幫助開發者輕鬆建立、釋出、維護 API，YApi 還為使用者提供了優秀的互動體驗，開發人員只需利用平臺提供的介面資料寫入工具以及簡單的點選操作就可以實現介面的管理。

主頁：^[1]

GitHub：^[2]

特性

• 基於 Json5 和 Mockjs 定義介面返回資料的結構和文件，效率提升多倍
• 扁平化許可權設計，即保證了大型企業級專案的管理，又保證了易用性
• 類似 postman 的介面除錯
• 自動化測試, 支援對 Response 斷言
• MockServer 除支援普通的隨機 mock 外，還增加了 Mock 期望功能，根據設定的請求過濾規則，返回期 望資料
• 支援 postman, har, swagger 資料匯入
• 免費開源，內網部署，資訊再也不怕洩露了

主頁面

API 基本資訊

引數和響應

Swagger

介紹

Swagger 是一個規範且完整的框架，用於生成、描述、呼叫和視覺化 RESTful 風格的 Web 服務。Swagger 的目標是對 REST API 定義一個標準且和語言無關的介面，可讓人和計算機擁有無需訪問原始碼、文件或網路流量監測就可以發現和理解服務的能力。當透過 Swagger 進行正確定義，使用者可以理解遠端服務並使用最少實現邏輯與遠端服務進行互動。與為底層程式設計所實現的介面類似，Swagger 消除了呼叫服務時可能會有的猜測。

GitHub：^[3]

整合

在 Spring Boot 中可以使用開源的 starter 包來進行整合會更簡單，比如我們用 spring4all 的這個封裝，Maven 依賴如下：

<dependency>
    <groupId>com.spring4all</groupId>
    <artifactId>swagger-spring-boot-starter</artifactId>
    <version>1.9.1.RELEASE</version>
</dependency>

依賴加好後在啟動類上加@EnableSwagger2Doc 來啟用 Swagger。

使用

使用的話就不具體講解了，也比較簡單，就是在你的介面上加一些註解來描述這個介面是幹嘛的就可以了。

預設不加註解也能將你的介面全部顯示出來，也就是掃描了你的@RestController 中的方法。

有可能會遇到的問題

一般我們會在專案中進行全域性的異常處理，當發生錯誤時，將異常捕獲然後轉換成固定的格式響應給呼叫方，這樣可以統一 API 的資料格式。

我們會配置下面的內容，告訴 SpringBoot 不要為我們工程中的資原始檔建立對映，這樣就可以返回純 JSON 的內容。

spring.resources.add-mappings=false

但是這樣的話我們的 swagger-ui.html 就不能訪問了，所以需要對 swagger-ui.html 相關的資源單獨進行對映。

@Configuration
public class WebAppConfigurer extends WebMvcConfigurationSupport {    
    @Override    
    protected void addResourceHandlers(ResourceHandlerRegistry registry) {
        registry.addResourceHandler("/swagger-ui.html")                
                .addResourceLocations("classpath:/META-INF/resources/");        
        registry.addResourceHandler("/webjars/**")                
                .addResourceLocations("classpath:/META-INF/resources/webjars/");                super.addResourceHandlers(registry);
    }
}

ShowDoc

ShowDoc 是一個非常適合 IT 團隊的線上 API 文件、技術文件工具。

主頁：^[4]

GitHub：^[5]

我們可以用 ShowDoc 來做 API 文件，資料字典，說明文件等用途。可以自己進行部署，個人的話也可以使用官方提供的線上示列。

ShowDoc 支援許可權管理，支援 markdown 編輯，支援匯出，支援分享等功能。

API 文件

資料字典

CRAP-API

CRAP-API 是完全開源、免費的 API 協作管理系統。提供協作開發、線上測試、文件管理、匯出介面、個性化功能定製等功能。

主頁：^[6]

GitHub：^[7]

特性

• 簡單高效的 BUG 管理系統，記錄每一次變動
• 團隊協作、許可權控制、修改日誌
• 資料庫表、markdown、restful、mock、pdf、word
• 開源 chrome 外掛，支援跨域、本地、線上介面除錯
• 系統完全免費、完全開源

API 管理

資料字典

資料字典還支援生成 MyBatis 的 XML 檔案，生成 Java 的 Entity 物件。

參考資料