一百七十七

ouhou999發表於2020-12-28

一、是什麼
　　當下很多公司都採取前後端分離的開發模式，前端和後端的工作由不同的工程師完成。在這種開發模式下，維持一份及時更新且完整的 Rest API 文件將會極大的提高我們的工作效率。傳統意義上的文件都是後端開發人員手動編寫的，相信大家也都知道這種方式很難保證文件的及時性，這種文件久而久之也就會失去其參考意義，反而還會加大我們的溝通成本。而 Swagger 給我們提供了一個全新的維護 API 文件的方式。

二、為什麼要使用它
　　1、程式碼變更，文件跟著程式碼變、只需要少量的註解Swagger就可以根據程式碼自動的生成API文件，很好的保證了文件的實時性。

2、跨語言，Swagger支援40多種語言。

3、Swagger UI 呈現出來的是一份可以互動的API文件，我們可以直接在文件頁面嘗試API的呼叫，省去了準備複雜的呼叫引數的過程。

4、還可以將文件規範匯入相關的工具裡面（例如：Postman、SoapUI）、這些工具將會為我們自動地建立自動化測試。

三、怎麼用
　　1、在專案pom.xml裡面加入Swagger2相關的依賴
複製程式碼

io.springfox
springfox-swagger-ui
2.4.0

io.springfox
springfox-swagger2
2.4.0

com.github.xiaoymin
swagger-bootstrap-ui
1.6

複製程式碼
　　2、新建Swagger2的配置類
複製程式碼
package com.zhouhong.config;

import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import springfox.documentation.builders.ApiInfoBuilder;
import springfox.documentation.builders.PathSelectors;
import springfox.documentation.builders.RequestHandlerSelectors;
import springfox.documentation.service.ApiInfo;
import springfox.documentation.service.Contact;
import springfox.documentation.spi.DocumentationType;
import springfox.documentation.spring.web.plugins.Docket;
import springfox.documentation.swagger2.annotations.EnableSwagger2;
/**

@ClassName: Swagger2
@Description:
@Author: 周紅
@NickName: Tom-shuhu
@Date: Created in 2020/12/15
**/
@Configuration
@EnableSwagger2
public class Swagger2 {
// http://localhost:8088/swagger-ui.html 原路徑
// http://localhost:8088/doc.html 原路徑
//配置swagger2核心配置
@Bean
public Docket createRestApi(){
return new Docket(DocumentationType.SWAGGER_2) //指定api型別位swagger2
.apiInfo(apiInfo()) //用於定義api文件彙總資訊
.select().apis(RequestHandlerSelectors
.basePackage(“com.zhouhong.controller”)) //指定生成文件的controller
.paths(PathSelectors.any())　　　　　　
.build();
}
private ApiInfo apiInfo(){
return new ApiInfoBuilder()
.title(“Tom-shushu 的專案介面api”) //文件標題
.contact(new Contact(“周紅”, //作者
“www.zhouhong.icu”,　　
“15249239025@163.com”)) //聯絡人
.description(“Tom-shushu 的專案api介面”)//詳細資訊
.version(“1.0.0”)//文件版本號
.termsOfServiceUrl(“www.zhouhong.icu”)//網站地址
.build();
}
}
複製程式碼
　　文件配置說明：

a.為任何介面生成API文件，這種方式不必在介面方法上加任何註解，方便的同時也會因為沒有新增任何註解所以生成的API文件也沒有註釋，可讀性不高。

複製程式碼
@Bean
public Docket createRestApi(){
return new Docket(DocumentationType.SWAGGER_2)
.apiInfo(apiInfo())
.select()
//為任何介面生成API文件
.apis(RequestHandlerSelectors.any())
.paths(PathSelectors.any())
.build();
}
複製程式碼
　　b.為當前配置的包下controller生成API文件

.apis(RequestHandlerSelectors.basePackage(“com.troila”))
　　c.為有@Api註解的Controller生成API文件

.apis(RequestHandlerSelectors.withClassAnnotation(Api.class))
　　d.為有@ApiOperation註解的方法生成API文件

.apis(RequestHandlerSelectors.withMethodAnnotation(ApiOperation.class))
三、常見註解簡介
複製程式碼
@Api：修飾整個類，描述Controller的作用
@ApiOperation：描述一個類的一個方法，或者說一個介面
@ApiParam：單個引數描述
@ApiModel：用物件實體來作為入參
@ApiProperty：用物件接實體收引數時，描述物件的一個欄位
@ApiResponse：HTTP響應其中1個描述
@ApiResponses：HTTP響應整體描述
@ApiIgnore：使用該註解忽略這個API
@ApiError ：發生錯誤返回的資訊
@ApiImplicitParam：一個請求引數
@ApiImplicitParams：多個請求引數
複製程式碼
四、演示（為方便我使用了上面第一種配置）
　　1、使用原路徑訪問

2、原路徑除錯

3、doc模式訪問

4、doc模式除錯