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

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

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

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

今天給你們推薦一個開源的API管理工具，若是尚未用上的感受看看吧。

YAPI

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

主頁：http://yapi.demo.qunar.com/

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

特性

• 基於 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

集成

在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/

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

咱們能夠用ShowDoc來作API文檔，數據字典，說明文檔等用途。能夠本身進行部署，我的的話也可使用官方提供的在線示列。

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

API文檔

數據字典

CRAP-API

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

主頁：http://api.crap.cn/

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

特性

• 簡單高效的BUG管理系統，記錄每一次變更
• 團隊協做、權限控制、修改日誌
• 數據庫表、markdown、restful、mock、pdf、word
• 開源chrome插件，支持跨域、本地、在線接口調試
• 系統徹底免費、徹底開源

API管理

新增API

數據字典

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