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

時間 2020-03-24

標籤爲我開發 api 添加華麗外衣简体版

原文原文鏈接

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

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

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

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

YAPI

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

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

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-apiapi

集成

在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);
        
    }
    
}