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

本文轉載自查看原文 2020-03-23 22:49 799

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

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

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

今天給大家推薦一個開源的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);
        
    }
    
}