---

前言

作為后端開放人員，最煩的事就是自己寫接口文檔和別人沒有寫接口文檔，不管是前端還是后端開發，多多少少都會被接口文檔所折磨，前端會抱怨后端沒有及時更新接口文檔，而后端又會覺得編寫接口文檔太過麻煩。Swagger 可以較好的接口接口文檔的交互問題，以一套標準的規范定義接口以及相關的信息，就能做到生成各種格式的接口文檔，生成多種語言和客戶端和服務端的代碼，以及在線接口調試頁面等等。只需要更新 Swagger 描述文件，就能自動生成接口文檔，做到前端、后端聯調接口文檔的及時性和便利性。

一、簡介

官網：https://swagger.io/

Swagger 是一個規范且完整的框架，用于生成、描述、調用和可視化 RESTful 風格的 Web 服務。

Swagger 的目標是對 REST API 定義一個標準且和語言無關的接口，可以讓人和計算機擁有無須訪問源碼、文檔或網絡流量監測就可以發現和理解服務的能力。當通過 Swagger 進行正確定義，用戶可以理解遠程服務并使用最少實現邏輯與遠程服務進行交互。與為底層編程所實現的接口類似，Swagger 消除了調用服務時可能會有的猜測。

Swagger 的優勢

• 支持 API 自動生成同步的在線文檔：使用 Swagger 后可以直接通過代碼生成文檔，不再需要自己手動編寫接口文檔了，對程序員來說非常方便，可以節約寫文檔的時間去學習新技術。
• 提供 Web 頁面在線測試 API：光有文檔還不夠，Swagger 生成的文檔還支持在線測試。參數和格式都定好了，直接在界面上輸入參數對應的值即可在線測試接口。

二、基本使用

1. 導入相關依賴

通過在項目中引入 Springfox，可以掃描相關的代碼，生成該描述文件，進而生成與代碼一致的接口文檔和客戶端代碼。

 <!-- swagger --> <dependency> <groupId>io.springfox</groupId> <artifactId>springfox-spring-web</artifactId> <version>2.9.2</version> </dependency> <dependency> <groupId>io.springfox</groupId> <artifactId>springfox-swagger2</artifactId> <version>2.9.2</version> </dependency> <dependency> <groupId>io.springfox</groupId> <artifactId>springfox-swagger-ui</artifactId> <version>2.9.2</version> </dependency> 

    




    

        1
    

    

        2
    

    

        3
    

    

        4
    

    

        5
    

    

        6
    

    

        7
    

    

        8
    

    

        9
    

    

        10
    

    

        11
    

    

        12
    

    

        13
    

    

        14
    

    

        15
    

    

        16
    

2. 編寫配置文件

在配置文件 config 目錄下，添加 swagger 的配置文件 SwaggerConfig.java

@Configuration // 配置類 @EnableSwagger2 // 開啟 swagger2 的自動配置 public class SwaggerConfig { } 


    

        1
    

    

        2
    

    

        3
    

    

        4
    

這個時候 Swagger 已經算是整合到項目之中了，可以啟動下服務，輸入：http://localhost:8080/swagger-ui.html# （這里我的項目端口是 8868 ，項目路徑是 /mike，所以我打開的文檔地址為 http://localhost:8868/mike/swagger-ui.html# ）即可查看 swagger 文檔。

可以看到 Swagger 文檔中大概有這四類信息

• 組
• 基本信息
• 接口信息
• 實體類信息

2.1 配置基本信息

Swagger 有自己的實例 Docket，如果我們想要自定義基本信息，可以使用 docket 來配置 swagger 的基本信息，基本信息的設置在 ApiInfo 這個對象中。

Swagger 默認的基本信息展示

ApiInfo 中默認的基本設置

• title：Api Documentation
• description：Api Documentation
• version：1.0
• termsOfServiceUrl：urn:tos
• contact：無
• license：Apache 2.0
• licenseUrl：http://www.apache.org/licenses/LICENSE-2.0

SwaggerConfig.java 配置文件添加以下內容：

 @Bean public Docket docket() { // 創建一個 swagger 的 bean 實例 return new Docket(DocumentationType.SWAGGER_2) // 配置基本信息 .apiInfo(apiInfo()) ; } // 基本信息設置 private ApiInfo apiInfo() { Contact contact = new Contact( "米大傻", // 作者姓名 "https://blog.csdn.net/xhmico?type=blog", // 作者網址 "777777777@163.com"); // 作者郵箱 return new ApiInfoBuilder() .title("多加辣-接口文檔") // 標題 .description("眾里尋他千百度，慕然回首那人卻在燈火闌珊處") // 描述 .termsOfServiceUrl("https://www.baidu.com") // 跳轉連接 .version("1.0") // 版本 .license("Swagger-的使用(詳細教程)") .licenseUrl("https://blog.csdn.net/xhmico/article/details/125353535") .contact(contact) .build(); } 

    




    

        1
    

    

        2
    

    

        3
    

    

        4
    

    

        5
    

    

        6
    

    

        7
    

    

        8
    

    

        9
    

    

        10
    

    

        11
    

    

        12
    

    

        13
    

    

        14
    

    

        15
    

    

        16
    

    

        17
    

    

        18
    

    

        19
    

    

        20
    

    

        21
    

    

        22
    

    

        23
    

    

        24
    

    

        25
    

重啟服務，打開 Swagger 文檔，基本信息改變如下所示：

2.2 配置接口信息

默認情況下，Swagger 是會展示所有的接口信息的，包括最基礎的 basic-error 相關的接口

有時候我們希望不要展示 basic-error-controller 相關的接口，或者是說這想要顯示某些接口，比如說：user-controller 下的接口，由該怎么去實現呢？這個時候就需要設置 掃描接口

 @Bean public Docket docket() { // 創建一個 swagger 的 bean 實例 return new Docket(DocumentationType.SWAGGER_2) // 配置接口信息 .select() // 設置掃描接口 // 配置如何掃描接口 .apis(RequestHandlerSelectors //.any() // 掃描全部的接口，默認 //.none() // 全部不掃描 .basePackage("com.duojiala.mikeboot.controller") // 掃描指定包下的接口，最為常用 //.withClassAnnotation(RestController.class) // 掃描帶有指定注解的類下所有接口 //.withMethodAnnotation(PostMapping.class) // 掃描帶有只當注解的方法接口 ) .paths(PathSelectors .any() // 滿足條件的路徑，該斷言總為true //.none() // 不滿足條件的路徑，該斷言總為false（可用于生成環境屏蔽 swagger） //.ant("/user/**") // 滿足字符串表達式路徑 //.regex("") // 符合正則的路徑 ) .build(); } 

    




    

        1
    

    

        2
    

    

        3
    

    

        4
    

    

        5
    

    

        6
    

    

        7
    

    

        8
    

    

        9
    

    

        10
    

    

        11
    

    

        12
    

    

        13
    

    

        14
    

    

        15
    

    

        16
    

    

        17
    

    

        18
    

    

        19
    

    

        20
    

    

        21
    

    

        22
    

    

        23
    

    

        24
    

可根據自己的需求去設置對應的配置，這里我就不再一一贅述了，以上是我所設置的配置，重啟服務，打開 Swagger 文檔，接口信息改變如下所示：

可以看到之前 basic-error-controller 相關的接口已經沒有了

2.3 配置分組信息

Swagger 默認只有一個 default 分組選項，如果沒有設置，所有的接口都會顯示在 default `分組下，如果功能模塊和接口數量一多，就會顯得比較凌亂，不方便查找和使用。

swagger 文檔中組名默認是 default，可通過 .groupName(String )

 @Bean public Docket docket() { // 創建一個 swagger 的 bean 實例 return new Docket(DocumentationType.SWAGGER_2) .groupName("mike") // 修改組名為 "mike" ; } 


    

        1
    

    

        2
    

    

        3
    

    

        4
    

    

        5
    

    

        6
    

    

        7
    

修改后：

如果需要配置多個組的話，就需要配置多個 docket() 方法，這里我就簡單寫兩組，代碼如下：

 /**
     * 展示 controller 包下所有的接口
     */ @Bean public Docket docket1() { // 創建一個 swagger 的 bean 實例 return new Docket(DocumentationType.SWAGGER_2) .groupName("mike") // 修改組名為 "mike" // 配置接口信息 .select() // 設置掃描接口 // 配置如何掃描接口 .apis(RequestHandlerSelectors .basePackage("com.duojiala.mikeboot.controller") // 掃描指定包下的接口，最為常用 ) .paths(PathSelectors .any() // 滿足條件的路徑，該斷言總為true ) .build(); } /**
     * 展示路徑為 /error 的所有接口（基礎接口）
     */ @Bean public Docket docket2() { // 創建一個 swagger 的 bean 實例 return new Docket(DocumentationType.SWAGGER_2) .groupName("yank") // 修改組名為 "yank" // 配置接口信息 .select() // 設置掃描接口 // 配置如何掃描接口 .apis(RequestHandlerSelectors .any() // 掃描全部的接口，默認 ) .paths(PathSelectors .ant("/error") // 滿足字符串表達式路徑 ) .build(); } 

    




    

        1
    

    

        2
    

    

        3
    

    

        4
    

    

        5
    

    

        6
    

    

        7
    

    

        8
    

    

        9
    

    

        10
    

    

        11
    

    

        12
    

    

        13
    

    

        14
    

    

        15
    

    

        16
    

    

        17
    

    

        18
    

    

        19
    

    

        20
    

    

        21
    

    

        22
    

    

        23
    

    

        24
    

    

        25
    

    

        26
    

    

        27
    

    

        28
    

    

        29
    

    

        30
    

    

        31
    

    

        32
    

    

        33
    

    

        34
    

    

        35
    

    

        36
    

    

        37
    

    

        38
    

    

        39
    

重啟服務，打開 Swagger 文檔，接口信息改變如下所示：

組名為 mike 的文檔中只有 user-controller 相關的接口信息

組名為 yank 的文檔中只有 basic-error-controller 相關的接口信息

---

3. 控制 Swagger 的開啟

在開發或者測試環境下，我們開啟 swagger 會方便前端和后端的交互，但是如果在生產環境下也開啟 swagger 的話，是會將接口暴露出去的，有極大風險，如何讓 swagger 根據不同的環境來決定是否開啟？

這里我準備了四個項目的配置文件，dev、test、pro 三個環境的配置文件僅是端口上的不同

• application.yml -------------------------- 全局配置文件
• application-dev.yml -------------------- 開發環境配置文件
• application-test.yml -------------------- 測試環境配置文件
• application-pro.yml -------------------- 生產環境配置文件

application.yml 內容如下，用于指定選擇的環境：

spring: profiles: active: dev 


    

        1
    

    

        2
    

    

        3
    

可以通過代碼判斷此時是在什么環境：dev、test、pro，如果是在 pro 生產環境，則關閉 swagger。

 /**
     * swagger 配置
     * @param environment 環境
     */ @Bean public Docket docket(Environment environment) { // 設置環境范圍 Profiles profiles = Profiles.of("dev","test"); // 如果在該環境返回內則返回：true，反之返回 false boolean flag = environment.acceptsProfiles(profiles); // 創建一個 swagger 的 bean 實例 return new Docket(DocumentationType.SWAGGER_2) .enable(flag) // 是否開啟 swagger：true -> 開啟，false -> 關閉 ; } 

    




    

        1
    

    

        2
    

    

        3
    

    

        4
    

    

        5
    

    

        6
    

    

        7
    

    

        8
    

    

        9
    

    

        10
    

    

        11
    

    

        12
    

    

        13
    

    

        14
    

    

        15
    

    

        16
    

    

        17
    

在 application.yml 全局配置文件中環境指向 dev 時，是可以打開 swagger 的

如果我將 application.yml 全局配置文件中環境指向 pro 時，就不能打開 swagger 了，提示 Could not render e, see the console

4. 常用注解使用

之前有說 Swagger 會將接口請求或者相應的實體類信息展示在 Models 下的，比如我 UserController.java 下有一個接口如下所示：

 @PostMapping(value = "/query-user-info") public ResponseBean queryUserInfo(@RequestBody @Validated IdReq req) { return ResponseBean.success(userService.queryUserInfo(req)); } 


    

        1
    

    

        2
    

    

        3
    

    

        4
    

它的請求體是 IdReq，響應是 ResponseBean，Models 展示這兩個實體類信息如下：

前端可通過看這個 Models 知道后端定義實體類的信息。

@ApiModel

該注解是作用于類上面的，是用來描述類的一些基本信息的。

相關屬性：

• value：提供類的一個備用名，如果不設置，默認情況下將使用 class 類的名稱
• description：對于類，提供一個詳細的描述信息
• parent：這個屬性用于描述的是類的一些父類信息
• discriminator：這個屬性解釋起來比較麻煩，因為這個類主要體現在斷言當中
• subTypes：可以通過這個屬性，指定我們想要使用的子類

譬如：這個為給 IdReq 這個類添加該注解

@Data @NoArgsConstructor @AllArgsConstructor @ApiModel(value = "Id請求體") public class IdReq { private String id; } 


    

        1
    

    

        2
    

    

        3
    

    

        4
    

    

        5
    

    

        6
    

    

        7
    

可以看到這里的名字從 IdReq 變成 Id請求體 了

@ApiModelProperty

它的作用是添加和操作屬性模塊的數據。

該注解的使用詳情可參見博客：@ApiModelProperty注解的用法

這里我還是以 IdReq 類為例，為該類的屬性添加說明

@Data @NoArgsConstructor @AllArgsConstructor @ApiModel(value = "Id請求體") public class IdReq { @ApiModelProperty("主鍵id") private String id; } 


    

        1
    

    

        2
    

    

        3
    

    

        4
    

    

        5
    

    

        6
    

    

        7
    

    

        8
    

可以看到這里對該字段有一個備注說明。

@ApiOperation

該注解用來對某個方法/接口進行描述

該注解的使用詳情可參見博客：Swagger @ApiOperation 注解詳解

這里我以 UserController 下的接口為例：

 @PostMapping(value = "/query-user-info") @ApiOperation(value = "根據id查詢用戶詳情") public ResponseBean queryUserInfo(@RequestBody @Validated IdReq req) { return ResponseBean.success(userService.queryUserInfo(req)); } 


    

        1
    

    

        2
    

    

        3
    

    

        4
    

    

        5
    

可以看見該接口就多了對其的描述信息。

@ApiParam

該注解使用在方法上或者參數上，字段說明，表示對參數的添加元數據（說明或者是否必填等）

相關屬性：

• name：參數名
• value：參數說明
• required：是否必填

這里我以 UserController 下的接口為例：

 @PostMapping(value = "/query-user-infos") @ApiOperation(value = "條件查詢用戶信息") public ResponseBean queryUserInfos( // name 用戶名稱 不必填 @ApiParam(value = "用戶名稱", required = false) @RequestParam(required = false) String name, // gender 用戶性別 必填 @ApiParam(value = "用戶性別", required = true) @RequestParam(required = true) GenderEnum gender ) { return ResponseBean.success(userService.queryUserInfos(name,gender)); } 


    

        1
    

    

        2
    

    

        3
    

    

        4
    

    

        5
    

    

        6
    

    

        7
    

    

        8
    

    

        9
    

    

        10
    

這里會展示請求參數的備注信息，以及是否必填等。

5. 接口調用

使用 swagger 除了讓前后端交互變得方便，也讓接口的請求變得簡單，只需要填寫好請求所需要的參數信息，便可直接發起請求。

比如說接口 /user/query-user-info

點擊 Try it out

設置好請求所需的參數，點擊 Execute 執行

就能看到接口響應的結果了

接口 /user/query-user-infos 也差不多

---

三、進階使用

1. 添加請求頭

有時候我們的接口是需要獲取請求頭信息的，這樣的話就還需要在 swagger 配置中添加請求頭的配置。

 @Bean public Docket docket() { // 設置請求頭 List<Parameter> parameters = new ArrayList<>(); parameters.add(new ParameterBuilder() .name("token") // 字段名 .description("token") // 描述 .modelRef(new ModelRef("string")) // 數據類型 .parameterType("header") // 參數類型 .defaultValue("default value") // 默認值：可自己設置 .hidden(true) // 是否隱藏 .required(false) // 是否必須 .build()); // 創建一個 swagger 的 bean 實例 return new Docket(DocumentationType.SWAGGER_2) .groupName("mike") // 修改組名為 "mike" // 配置接口信息 .select() // 設置掃描接口 // 配置如何掃描接口 .apis(RequestHandlerSelectors .basePackage("com.duojiala.mikeboot.controller") // 掃描指定包下的接口，最為常用 ) .paths(PathSelectors .any() // 滿足條件的路徑，該斷言總為true ) .build() // 添加請求頭參數 .globalOperationParameters(parameters); } 

    




    

        1
    

    

        2
    

    

        3
    

    

        4
    

    

        5
    

    

        6
    

    

        7
    

    

        8
    

    

        9
    

    

        10
    

    

        11
    

    

        12
    

    

        13
    

    

        14
    

    

        15
    

    

        16
    

    

        17
    

    

        18
    

    

        19
    

    

        20
    

    

        21
    

    

        22
    

    

        23
    

    

        24
    

    

        25
    

    

        26
    

    

        27
    

    

        28
    

    

        29
    

    

        30
    

    

        31
    

比如接口：

 @GetMapping(value = "/get-token") @ApiOperation(value = "獲取請求頭中的token信息") public void getToken( @RequestHeader(value = "token",required = false) String token ) { // 直接獲取 token 信息 System.out.println("token = " + token); // 通過代碼獲取 ServletRequestAttributes servletRequestAttributes = (ServletRequestAttributes) RequestContextHolder.getRequestAttributes(); if (servletRequestAttributes != null) { HttpServletRequest request = servletRequestAttributes.getRequest(); String header = request.getHeader("token"); System.err.println("header = " + header); } } 

    




    

        1
    

    

        2
    

    

        3
    

    

        4
    

    

        5
    

    

        6
    

    

        7
    

    

        8
    

    

        9
    

    

        10
    

    

        11
    

    

        12
    

    

        13
    

    

        14
    

    

        15
    

    

        16
    

可以看到這個接口已經可以去設置請求頭了，調用接口

后端也能獲取到。

藍藍設計建立了UI設計分享群，每天會分享國內外的一些優秀設計，如果有興趣的話，可以進入一起成長學習，請加藍小助，微信號:ben_lanlan，報下信息，藍小助會請您入群。歡迎您加入噢~~希望得到建議咨詢、商務合作，也請與我們聯系01063334945。

分享此文一切功德，皆悉回向給文章原作者及眾讀者.
免責聲明：藍藍設計尊重原作者，文章的版權歸原作者。如涉及版權問題，請及時與我們取得聯系，我們立即更正或刪除。

藍藍設計( m.skdbbs.com )是一家專注而深入的界面設計公司，為期望卓越的國內外企業提供卓越的UI界面設計、BS界面設計 、 cs界面設計 、 ipad界面設計 、 包裝設計 、 圖標定制 、 用戶體驗 、交互設計、 網站建設 、平面設計服務、UI設計公司、界面設計公司、UI設計服務公司、數據可視化設計公司、UI交互設計公司、高端網站設計公司、UI咨詢、用戶體驗公司、軟件界面設計公司