爲我開發的API添加華麗的外衣

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

另一個就是文檔不齊全，這些接口是幹嘛的？參數是什麼意思？等等問題。

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

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

YAPI

YApi 是高效、易用、功能強大的 api 管理平臺，旨在爲開發、產品、測試人員提供更優雅的接口管理服務。可以幫助開發者輕鬆創建、發佈、維護 API，YApi 還爲用戶提供了優秀的交互體驗，開發人員只需利用平臺提供的接口數據寫入工具以及簡單的點擊操作就可以實現接口的管理。

主頁：http://yapi.demo.qunar.com/^[1]

GitHub：https://github.com/YMFE/yapi^[2]

特性

• 基於 Json5 和 Mockjs 定義接口返回數據的結構和文檔，效率提升多倍

• 扁平化權限設計，即保證了大型企業級項目的管理，又保證了易用性

• 類似 postman 的接口調試

• 自動化測試, 支持對 Response 斷言

• MockServer 除支持普通的隨機 mock 外，還增加了 Mock 期望功能，根據設置的請求過濾規則，返回期 望數據

• 支持 postman, har, swagger 數據導入

• 免費開源，內網部署，信息再也不怕泄露了

主頁面

API 基本信息

參數和響應

Swagger

介紹

Swagger 是一個規範且完整的框架，用於生成、描述、調用和可視化 RESTful 風格的 Web 服務。Swagger 的目標是對 REST API 定義一個標準且和語言無關的接口，可讓人和計算機擁有無需訪問源碼、文檔或網絡流量監測就可以發現和理解服務的能力。當通過 Swagger 進行正確定義，用戶可以理解遠程服務並使用最少實現邏輯與遠程服務進行交互。與爲底層編程所實現的接口類似，Swagger 消除了調用服務時可能會有的猜測。

GitHub：https://github.com/swagger-api^[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 文檔、技術文檔工具。

主頁：https://www.showdoc.cc/^[4]

GitHub：https://github.com/star7th/showdoc^[5]

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

ShowDoc 支持權限管理，支持 markdown 編輯，支持導出，支持分享等功能。

API 文檔

數據字典

CRAP-API

CRAP-API 是完全開源、免費的 API 協作管理系統。提供協作開發、在線測試、文檔管理、導出接口、個性化功能定製等功能。

主頁：http://api.crap.cn/^[6]

GitHub：https://github.com/EhsanTang/ApiManager^[7]

特性

• 簡單高效的 BUG 管理系統，記錄每一次變動

• 團隊協作、權限控制、修改日誌

• 數據庫表、markdown、restful、mock、pdf、word

• 開源 chrome 插件，支持跨域、本地、在線接口調試

• 系統完全免費、完全開源

API 管理

新增API

數據字典

數據字典還支持生成 MyBatis 的 XML 文件，生成 Java 的 Entity 對象。

參考資料

[1]

http://yapi.demo.qunar.com/: http://yapi.demo.qunar.com/

[2]

https://github.com/YMFE/yapi: https://github.com/YMFE/yapi

[3]

https://github.com/swagger-api: https://github.com/swagger-api

[4]

https://www.showdoc.cc/: https://www.showdoc.cc/

[5]

https://github.com/star7th/showdoc: https://github.com/star7th/showdoc

[6]

http://api.crap.cn/: http://api.crap.cn/

[7]

https://github.com/EhsanTang/ApiManager: https://github.com/EhsanTang/ApiManager

如有收穫，點個在看，誠摯感謝