一，整合Swagger3.0

隨着Spring Boot、Spring Cloud等微服務的流行，在微服務的設計下，小公司微服務工程jar小的幾十個，大公司大的工程拆分jar多則幾百上萬個，這麼多的微服務一定產生了大量的接口調用。而接口的調用就一定要寫接口文檔（由開發人員編寫）。html

存在的問題：（面對多個開發人員或多個開發團隊）spring

項目開發接口衆多，細節，複雜，且多樣化，高質量地建立接口文檔費時，費力。
隨着項目的進行，不可避免整改和優化，須要不斷的修改接口實現，伴隨着也須要同時修改接口文檔，管理不方便不說，還容易出現不一致的狀況。

概述

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

實際開發過程當中Swagger 可以完美地與Spring Boot程序整合，組織出強大RESTful API文檔，它既能夠減小咱們建立文檔的工做量，同時也整合了說明內容在實現代碼中，讓維護文檔和修改代碼融爲一體，可讓咱們在修改代碼邏輯的同時方便的修改文檔說明。另外Swagger2還提供了強大的頁面測試功能，讓開發者能快速地調試每一個RESTful API。api

1.整合實現

1，引入pom依賴。

Swagger3.0的更新仍是有很大變化的（詳情參考），首先在依賴jar問題上，它新增了springfox-boot-starter，修復了2.x版本的衝突，移除了guava。另外Swagger3.0還移除了註解@EnableSwagger2，增長註解@EnableOpenApi。瀏覽器

<!-- SpringBoot整合springfox-swagger3 -->
<dependency>
    <groupId>io.springfox</groupId>
    <artifactId>springfox-boot-starter</artifactId>
    <version>3.0.0</version>
</dependency>

啓動SpringBoot主程序，能夠直接測試訪問：服務器

測試地址：http://localhost:8080/swagger-ui/index.html （訪問後提供的有默認的錯誤調用接口文檔）restful

須要注意的是，Swagger3.0還更新了UI頁面地址，如上，而Swagger2.x的訪問地址是這樣的：http://localhost:8080/swagger-ui.html架構

2，自定義SwaggerConfig類

新增SwaggerConfig類，並將其加載到Spring IOC中。須要注意：自定義Swagger配置類，Swagger3.0移除註解@EnableSwagger2，增長註解@EnableOpenApi。@EnableOpenApi能夠在Config類中應用，也能夠在SpringBoot主啓動類上使用（選其一便可），表示啓用自定義API接口。app

1 @EnableOpenApi   // 開啓Swagger自定義接口文檔
 2 @Configuration   // 至關於Spring配置中的<beans>
 3 public class SwaggerConfig {
 4     @Bean   // 至關於Spring 配置中的<bean>
 5     public Docket createRestApi() {
 6         return new Docket(DocumentationType.OAS_30)
 7                 .apiInfo(apiInfo())
 8                 .select()
 9                 .apis(RequestHandlerSelectors.withMethodAnnotation(ApiOperation.class)) 10 .paths(PathSelectors.any()) 11 .build();
12     }
13     // API基礎信息定義（就是更新Swagger默認頁面上的信息）
14     private ApiInfo apiInfo() {
15         return new ApiInfoBuilder()
16                 .title("Swagger3接口文檔測試")
17                 .description("文檔描述：更多問題，請聯繫開發者")
18                 .contact(new Contact("xsge123（name）", "做者網站(url)", "1511868921@qq.com(email)"))
19                 .version("1.0")
20                 .build();
21     }
22     
23 }

3，編寫Controller提供RESTful風格的接口API

編寫Controller前，先看看一些註解的意思吧！框架

@Api：用在控制器類上，表示對類的說明
    tags="說明該類的做用，能夠在UI界面上看到的說明信息的一個好用註解"
    value="該參數沒什麼意義，在UI界面上也看到，因此不須要配置"

@ApiOperation：用在請求的方法上，說明方法的用途、做用
    value="說明方法的用途、做用"
    notes="方法的備註說明"

@ApiImplicitParams：用在請求的方法上，表示一組參數說明
    @ApiImplicitParam：用在@ApiImplicitParams註解中，指定一個請求參數的各個方面（標註一個指定的參數，詳細歸納參數的各個方面，例如：參數名是什麼？參數意義，是否必填等）
        name：屬性值爲方法參數名
        value：參數意義的漢字說明、解釋
        required：參數是否必須傳
        paramType：參數放在哪一個地方
            · header --> 請求參數的獲取：@RequestHeader
            · query --> 請求參數的獲取：@RequestParam
            · path（用於restful接口）--> 請求參數的獲取：@PathVariable
            · div（不經常使用）
            · form（不經常使用）    
        dataType：參數類型，默認String，其它值dataType="Integer"       
        defaultValue：參數的默認值

@ApiResponses：用在請求的方法上，表示一組響應
    @ApiResponse：用在@ApiResponses中，通常用於表達一個錯誤的響應信息
        code：狀態碼數字，例如400
        message：信息，例如"請求參數沒填好"
        response：拋出異常的類

@ApiModel：用於響應類上（POJO實體類），描述一個返回響應數據的信息（描述POJO類請求或響應的實體說明）
            （這種通常用在post接口的時候，使用@RequestBody接收JSON格式的數據的場景，請求參數沒法使用@ApiImplicitParam註解進行描述的時候）
    @ApiModelProperty：用在POJO屬性上，描述響應類的屬性說明
@ApiIgnore：使用該註解忽略這個API；

Spring Boot中包含了一些控制器方法RESTful接口註解，對應於HTTP協議中的方法：

@GetMapping對應HTTP中的GET方法；
@PostMapping對應HTTP中的POST方法；
@PutMapping對應HTTP中的PUT方法；
@DeleteMapping對應HTTP中的DELETE方法；
@PatchMapping對應HTTP中的PATCH方法。

1 @Api(value = "測試SwaggerAPI Annotation", tags = "Swagger測試之用戶信息管理API")
 2 @RestController
 3 @RequestMapping("/user")
 4 public class SwaggerController {
 5     
 6     @ApiIgnore    // 忽略這個API
 7     @GetMapping("/hello")
 8     public String hello() {
 9         return "hello";
10     }
11     
12     @GetMapping(value = "/swaggerGet/{name}")
13     @ApiOperation(value = "接口方法說明", notes = "接口的詳情描述")
14     @ApiImplicitParam(name = "name", value = "請傳遞一個用戶名參數",required = true, dataType = "String", paramType = "path")
15     public String swaggerGet(@PathVariable  String name) {
16         return "name="+name;
17     }
18     
19     @PostMapping(value = "/swaggerPost")
20     @ApiOperation(value = "新增用戶", notes = "Swagger測試RESTful之POST請求測試入參一個POJO（JSON格式）")
21     public User swaggerGet(@RequestBody User user) {
22         return user;
23     }
24     
25 }

實體類

1 @ApiModel("用戶信息實體類")
 2 @Data
 3 public class User {
 4     // example:示例代碼值
 5     @ApiModelProperty(value = "用戶名",dataType="String",name="username",example="xsge")
 6     private String username;
 7     @ApiModelProperty(value = "帳戶密碼",dataType="String",name="password",example="123456")
 8     private String password;
 9     
10 }

4，啓動SpringBoot工程，測試訪問

　　輸入地址：http://localhost:8080/swagger-ui/index.html 進入Swagger接口文檔界面。

　　注意：Swagger2.x版本不同哦！關於2.x的配置版本也有些不一樣，這裏就不介紹了...

二，統一接口返回值

咱們在應用中常常會涉及到 server 和 client 的交互，目前比較流行的是基於 json 格式的數據交互。可是 json 只是消息的格式，其中的內容還須要咱們自行設計。不論是 HTTP 接口仍是 RPC 接口保持返回值格式統一很重要，這將大大下降 client 的開發成本。

通常定義Response的標準格式包含四部分：

Integer code ；成功時返回 0 ，失敗時返回具體錯誤碼。（能夠自定義錯誤碼，使用枚舉類封裝）
String message ；成功時返回 null ，失敗時返回具體錯誤消息。（能夠自定義錯誤消息，使用枚舉類封裝）
T data ；成功時具體返回值，失敗時爲 null 。

例如：

1 {
2     "code": 0,
3     "messages": "",
4     "data": ""
5 }

1.定義枚舉類，封裝狀態碼和消息

定義一些常見的成功與失敗的枚舉常量。以下：（該枚舉類能夠做爲工具使用了，有心的朋友可自行保存一下）

1 public enum EnumCode {
 2     // 定義成功的枚舉常量，狀態碼，和描述
 3     SUCCESS(0,"ok"),// 這裏的代碼至關於：public static final DataEnumCode SUCCESS = new DataEnumCode(0,「ok」)調用類有參構造傳值
 4     // 定義系統異常的枚舉常量，狀態碼，和描述
 5     SYSTEM_ERROR(5001,"服務器系統異常，請稍後..."),
 6     // 定義參數異常的枚舉常量，狀態碼，和描述
 7     PARAMETER_ERROR(5002,"參數異常，認證失敗..."),
 8     // 定義用戶名存在異常的枚舉常量，狀態碼，和描述
 9     USER_HAS_ERROR(5003,"用戶名已存在....");// 注意上面的是逗號分隔，這裏結束是分號
10     
11     // 定義的枚舉常量屬性。
12     private int code;// 狀態碼
13     private String message;// 描述
14     
15     /** 16 * 私有構造,防止被外部調用 17 */
18     private EnumCode(int code, String message) {
19         this.code = code;
20         this.message = message;
21     }
22      /** 23 * 定義方法,返回描述,跟常規類的定義get沒區別 24 * @return 25 */
26     public int getCode() {
27         return code;
28     }
29     public String getMessage() {
30         return message;
31     }
32 }

2.定義Response的標準格式POJO

爲便於合理化實現標準格式的響應，新增POJO類，並添加封裝屬性（狀態碼，描述信息，響應數據）。

爲便於標準化的實施，類中提供的以下四個方法：（該解析響應類能夠做爲工具使用了，有心的朋友可自行保存一下）

成功方法。請求成功，響應結果集數據，響應狀態碼，描述，狀態碼和描述從枚舉常量中解析。
失敗方法。請求失敗，無結果集數據，響應狀態碼，描述保留，狀態碼和描述從枚舉常量中解析。（枚舉類型有限，不必定知足全部異常）
失敗方法。請求失敗，無結果集數據，響應狀態碼，描述保留，該方法用於解決由於枚舉常量的侷限性，不足以知足全部需求的問題，實現容許自定義狀態碼和描述。
提供便於解析枚舉常量的方法。

1 @Data
 2 @NoArgsConstructor
 3 @AllArgsConstructor
 4 public class ResponseData<T> {
 5 
 6     private int code;// 狀態碼
 7     private String message;// 提示消息
 8     private T data;// 響應結果集數據
 9 
10     /**枚舉類常量解析器
11      * 快速解析枚舉類常量信息，解析數據並放入到標準響應類ResponseData的屬性中
12      * @param enumCode
13      */
14     public void parserEnum(EnumCode enumCode) {
15         this.code = enumCode.getCode();// 獲取枚舉常量的狀態碼，賦值給屬性
16         this.message = enumCode.getMessage();// 獲取枚舉常量的描述信息
17     }
18 
19     /**定義請求成功的：狀態碼，描述，結果集數據
20      * @param data 傳遞的響應結果集數據
21      * @return 有成功狀態碼，描述，結果集數據的標準格式對象
22      */
23     public static<T> ResponseData<T> success(T data) {
24         // 建立響應標準格式對象
25         ResponseData<T> responseData = new ResponseData<T>();
26         // 調用轉換器方法，將（成功）枚舉常量解析，放入到標準響應數據中。
27         responseData.parserEnum(EnumCode.SUCCESS);
28         // 放入響應數據
29         responseData.setData(data);
30         return responseData;
31     }
32 
33 
34     /**定義請求失敗的：狀態碼，描述，不包含結果集數據
35      * @param enumCode 失敗時傳遞的常見錯誤枚舉常量
36      * @return 有失敗狀態碼，描述，沒有結果集數據的標準格式對象
37      */
38     public static<T> ResponseData<T> error(EnumCode enumCode) {
39         // 建立響應標準格式對象
40         ResponseData<T> responseData = new ResponseData<T>();
41         // 調用轉換器方法，將（錯誤）枚舉常量解析。
42         responseData.parserEnum(enumCode);
43         return responseData;
44     }
45 
46     /** 有成功，有失敗，可是失敗的狀態描述不必定能所有知足需求（枚舉類有限），因此，自定義方法實現自定義信息
47      * @param code 自定義的狀態碼
48      * @param message 自定義的錯誤信息
49      * @return 有失敗自定義狀態碼，自定義描述，沒有結果集數據的標準格式對象
50      */
51      public static<T> ResponseData<T> generator(int code,String message) {
52         // 建立響應標準格式對象
53         ResponseData<T> responseData = new ResponseData<T>();
54         responseData.setCode(code);
55         responseData.setMessage(message);
56         return responseData;
57     }
58 
59 }

舒適提示：靜態方法定義泛型時，必須使用statc<T>定義，不然編譯失敗。

解惑：有人可能存在疑問，既然枚舉類不能知足全部響應要求，幹嗎定義枚舉類，感受有點畫蛇添足！直接自定義封裝多好，能夠解決全部問題。可是，請記住，團隊開發，若是所有使用自定義封裝，那麼如何實現信息的統一標準呢？當出現同一個錯誤時，有人提示系統錯誤，有人提示後臺錯誤，有人提示請聯繫管理員？？？這樣是否是很亂。因此常見的，基本的消息定義，經過枚舉類列舉，能夠輕鬆實現統一管理。而不常見的錯誤，既然不常見，那麼又怎可能常常自定義？這就是簡易的架構設計優化。

3，編寫Controller提供RESTful風格暴露接口

1 @Api(value = "測試SwaggerAPI Annotation", tags = "Swagger測試之用戶信息管理API")
 2 @RestController
 3 @RequestMapping("/user")
 4 public class SwaggerController {
 5     
 6     @ApiIgnore    // 忽略這個API
 7     @GetMapping("/hello")
 8     public String hello() {
 9         return "hello";
10     }
11     
12     @GetMapping(value = "/swaggerGet/{name}")
13     @ApiOperation(value = "接口方法說明", notes = "接口的詳情描述")
14     @ApiImplicitParam(name = "name", value = "請傳遞一個用戶名參數",required = false,dataType = "String", paramType = "path")
15     public ResponseData<String> swaggerGet(@PathVariable String name) {
16         // 調用成功的解析方法，並傳遞響應數據
17         ResponseData<String> responseData = ResponseData.success(name);
18         return responseData;
19     }
20     
21     @PostMapping(value = "/swaggerPost")
22     @ApiOperation(value = "新增用戶", notes = "Swagger測試RESTful之POST請求測試入參一個POJO（JSON格式）")
23     public ResponseData<User> swaggerGet(@RequestBody User user) {
24         // 調用成功的解析方法，並傳遞響應數據
25         ResponseData<User> responseData = ResponseData.success(user);
26         return responseData;
27     }
28     
29 }

4.打開瀏覽器測試訪問。瀏覽器測試訪問：http://localhost:8080/swagger-ui/index.html （選擇測試一下，按照接口文檔說明實施測試）

Postman測試訪問：（輸入接口URL，傳遞參數測試便可）

測試結果以下：

原文連接： https://www.cnblogs.com/xsge/p/13996625.html

SpringBoot：整合Swagger3.0與RESTful接口整合返回值（2020最新最易懂）