個(gè)人學(xué)習(xí)筆記分享，當(dāng)前能力有限，請(qǐng)勿貶低，菜鳥(niǎo)互學(xué)，大佬繞道
如有勘誤，歡迎指出和討論，本文后期也會(huì)進(jìn)行修正和補(bǔ)充
前言
使用Swagger可以方便快捷的查看和調(diào)試接口，而不再需要借助其他第三方工具（如postman），更不需要在茫茫代碼中尋找接口，其相關(guān)注解也一定程度上提高了代碼可讀性。
因此，swagger幾乎已經(jīng)算的上是一個(gè)項(xiàng)目的必要組件了。
1.介紹
1.1.Swagger、Spring、SpringFox
-
Swagger是一個(gè)流行的API框架，對(duì)整個(gè)API開(kāi)發(fā)周期提供解決方案，包括設(shè)計(jì)、編碼和測(cè)試等等，幾乎支持所有語(yǔ)言。 -
Spring作為常用的Java開(kāi)發(fā)框架，不做多余敘述 -
SpringFox是一個(gè)基于Spring的組件，用于Swagger集成至SpringMVC，后發(fā)展至SpringFox，Springfox-swagger2則是其中一個(gè)組件 -
Springfox-Swagger-UI顧名思義則是一個(gè)UI組件，用于展示相關(guān)數(shù)據(jù)
總結(jié)：
-
Swagger是API解決方案 -
Spring是Java框架 -
SpringFox是基于Java的Swagger實(shí)現(xiàn) -
Springfox-Swagger-UI是配套的UI
1.2.用途
- 前后端分離：前端只需要通過(guò)
Swagger即可查找并調(diào)試接口 - API整理：暴露給外部的接口全部展示在
Swagger，方便查找和整理 - 增強(qiáng)代碼可讀性：相關(guān)注解在后端也會(huì)使代碼可讀性更好，相當(dāng)于充當(dāng)了注釋的作用
2.集成
目前
SpringFox已經(jīng)更新至3.0版本，修復(fù)了大量問(wèn)題，關(guān)鍵是配置方法做出了改變，故將SpringFox2與SpringFox3分開(kāi)記錄
2.1.swagger2（主流版本）
-
添加依賴
<dependency> <groupId>io.springfox</groupId> <artifactId>springfox-swagger2</artifactId> <version>2.6.1</version> </dependency> <dependency> <groupId>io.springfox</groupId> <artifactId>springfox-swagger-ui</artifactId> <version>2.6.1</version> </dependency>前者為swagger2依賴，后者為ui，后者可以更換為其他ui，此處不做多述
-
創(chuàng)建swagger配置文件
@Configuration @EnableSwagger2 @Profile({"dev", "test"}) public class SwaggerConfig { @Bean // 配置docket以配置Swagger具體參數(shù) public Docket docket(Environment environment) { return new Docket(DocumentationType.SWAGGER_2) .apiInfo(apiInfo())// 關(guān)聯(lián)配置文檔 .enable(true)// 是否啟用 .select()//掃描方法 .apis(RequestHandlerSelectors.basePackage("com.yezi_tool.basic_project.controller"))//掃描包路徑 .paths(PathSelectors.any())//路徑過(guò)濾 .build();//構(gòu)建 } // 配置文檔信息 private ApiInfo apiInfo() { return new ApiInfoBuilder() .title("SpringBoot-Swagger2集成") .description("API描述") .contact("聯(lián)系人名字") .version("1.0") .build(); } } 啟動(dòng)項(xiàng)目后，打開(kāi)網(wǎng)址http://localhost:8080/swagger-ui.html，請(qǐng)自行修改端口和路徑
2.2.swagger3版本
-
添加依賴
<dependency> <groupId>io.springfox</groupId> <artifactId>springfox-boot-starter</artifactId> <version>3.0.0</version> </dependency>僅此一個(gè)依賴
-
創(chuàng)建swagger配置文件
@Configuration @EnableOpenApi @Profile({"dev", "test"}) public class Swagger3Config { @Bean // 配置docket以配置Swagger具體參數(shù) public Docket docket() { return new Docket(DocumentationType.OAS_30)//文檔類型 .apiInfo(apiInfo())// 關(guān)聯(lián)配置文檔 .select()//掃描方法 .apis(RequestHandlerSelectors.basePackage("com.yezi_tool.basic_project.controller"))//掃描包路徑 .paths(PathSelectors.any())//路徑過(guò)濾 .build();//構(gòu)建 } // 配置文檔信息 private ApiInfo apiInfo() { Contact contact = new Contact("聯(lián)系人名字", "http://xxx.xxx.com/聯(lián)系人訪問(wèn)鏈接", "聯(lián)系人郵箱"); return new ApiInfo( "Swagger學(xué)習(xí)", // 標(biāo)題 "學(xué)習(xí)演示如何配置Swagger", // 描述 "v1.0", // 版本 "http://terms.service.url/組織鏈接", // 組織鏈接 contact, // 聯(lián)系人信息 "Apach 2.0 許可", // 許可 "許可鏈接", // 許可連接 new ArrayList<>()// 擴(kuò)展 ); } } 啟動(dòng)項(xiàng)目后，打開(kāi)網(wǎng)址http://localhost:8080/swagger-ui/index.html，請(qǐng)自行修改端口和路徑
2.3.版本差異
- swagger3進(jìn)行了大量更新與修復(fù)，不做多述
- swagger3僅需一個(gè)依賴，將swagger和UI合并
- 配置文件的注解，swagger2需要
@EnableSwagger2，而swagger3需要@EnableOpenApi - 配置文件的
ApiInfo構(gòu)造方法變更，小問(wèn)題 - 項(xiàng)目默認(rèn)地址變更，swagger2的地址是
/swagger-ui.html，swagger3的地址是swagger-ui/index.html - 部分方法改動(dòng)，如2.5的全局參數(shù)
2.4.配置文件額外參數(shù)
通常上述參數(shù)已滿足需求，當(dāng)然還提供了其他參數(shù)供開(kāi)發(fā)者選擇，兩個(gè)版本的自定義參數(shù)基本一致
注解
@Profile：枚舉適用的運(yùn)行環(huán)境，通常僅在開(kāi)發(fā)環(huán)境和測(cè)試環(huán)境中啟用，則可使用@Profile({"dev", "test"})配置文檔信息：請(qǐng)根據(jù)需求修改，不做多述
-
docket對(duì)象方法
enable()：是否啟用swagger，參數(shù)為true/false，但通常用注解
@Profile控制-
api()：指定包掃描路徑，參數(shù)形如
RequestHandlerSelectors.basePackage("com.test.api")，也可以根據(jù)自身需求調(diào)整，其余形式參數(shù)如下- RequestHandlerSelectors.any()：掃描所有，項(xiàng)目中的所有接口都會(huì)被掃描到
- RequestHandlerSelectors.none() ：不掃描接口
- RequestHandlerSelectors.withMethodAnnotation(final Class<? extends Annotation> annotation)： 通過(guò)方法上的注解掃描，如withMethodAnnotation(GetMapping.class)只掃描get請(qǐng)求
- RequestHandlerSelectors.withClassAnnotation(final Class<? extends Annotation> annotation)： 通過(guò)類上的注解掃描，如.withClassAnnotation(Controller.class)只掃描有controller注解的類中的接口
- RequestHandlerSelectors.basePackage(final String basePackage) ： 根據(jù)包路徑掃描接口
-
paths()：指定url路徑過(guò)濾，參數(shù)形如
PathSelectors.ant("/login/**")，也可以根據(jù)自身需求調(diào)整，其余形式參數(shù)如下- PathSelectors.any()： 任何請(qǐng)求都掃描
- PathSelectors.none() ： 任何請(qǐng)求都不掃描
- PathSelectors.regex(final String pathRegex) ： 通過(guò)正則表達(dá)式控制
- PathSelectors.ant(final String antPattern) ： 通過(guò)ant()控制
groupName()：配置分組，參數(shù)為String字符串，如
group 1，默認(rèn)分組為default，如需設(shè)置多個(gè)分組，則實(shí)例化多個(gè)不同名的docket即可-
getGlobalOperationParameters：全局參數(shù)，不適用于swagger3，通常用于token，示例如下
ParameterBuilder ticketPar = new ParameterBuilder(); List<Parameter> pars = new ArrayList<Parameter>(); ticketPar.name("token") .description("token") .modelRef(new ModelRef("string")) .parameterType("header") .required(false) .build(); pars.add(ticketPar.build()); docket.globalOperationParameters(pars)
2.5.全局參數(shù)（重點(diǎn)）
通常用于設(shè)置token，swagger3修改了相關(guān)方法，所以此處均給出示例
-
swagger2版本
public Docket docket() { ... docket.globalOperationParameters(pars); ... } private List<Parameter> pars(){ List<Parameter> pars = new ArrayList<Parameter>(); ParameterBuilder ticketPar = new ParameterBuilder(); ticketPar.name("token") .description("token") .modelRef(new ModelRef("string")) .parameterType("header") .required(false) .build(); pars.add(ticketPar.build()); return pars; } -
swagger3版本
public Docket docket() { ... docket.protocols(new LinkedHashSet<>(Arrays.asList("https", "http")))// 支持的通訊協(xié)議集合 .securitySchemes(securitySchemes())// 授權(quán)信息設(shè)置，必要的header token等認(rèn)證信息 .securityContexts(securityContexts());// 授權(quán)信息全局應(yīng)用 ... } /** * 設(shè)置授權(quán)信息 */ private List<SecurityScheme> securitySchemes() { return Collections.singletonList(new ApiKey("BASE_TOKEN", "token", "pass")); } /** * 授權(quán)信息全局應(yīng)用 */ private List<SecurityContext> securityContexts() { return Collections.singletonList( SecurityContext.builder().securityReferences(Collections.singletonList(new SecurityReference("BASE_TOKEN", new AuthorizationScope[]{new AuthorizationScope("global", "")}))).build()); }
3.使用
相關(guān)注解
@Api：用在類上，說(shuō)明該類的作用。
@ApiOperation：注解來(lái)給API增加方法說(shuō)明。
@ApiImplicitParams : 用在方法上包含一組參數(shù)說(shuō)明。
@ApiImplicitParam：用來(lái)注解來(lái)給方法入?yún)⒃黾诱f(shuō)明。
@ApiResponses：用于表示一組響應(yīng)
-
@ApiResponse：用在@ApiResponses中，一般用于表達(dá)一個(gè)錯(cuò)誤的響應(yīng)信息
code：返回碼，例如400
message：信息，例如"參數(shù)錯(cuò)誤"
response：拋出異常的類
@ApiModel：描述一個(gè)Model的信息（一般用在請(qǐng)求參數(shù)無(wú)法使用@ApiImplicitParam注解進(jìn)行描述的時(shí)候）
@ApiModelProperty：描述一個(gè)model的屬性
@ApiIgnore：忽略某個(gè)api，可用于單個(gè)接口，也可用于整個(gè)controller
使用步驟
當(dāng)然一切的前提是先集成
-
添加注解
-
實(shí)體類添加注解，實(shí)例如下
@ApiModel("登錄信息實(shí)體") public class LoginRequest { @ApiModelProperty("用戶名") public String username; @ApiModelProperty("密碼") public String password; } -
控制器添加注解，實(shí)例如下
@Controller @RequestMapping("/testController") @Api(tags = "測(cè)試") public class TestController { } -
接口方法添加注解，實(shí)例如下
@ApiOperation("測(cè)試swagger") @PostMapping("/testSwagger") @ResponseBody public LoginRequest testSwagger(@ApiParam(required = false, value = "登錄實(shí)體") @RequestParam(required = false) @RequestBody LoginRequest loginRequest) throws Exception { if (loginRequest == null) { loginRequest = new LoginRequest(); } return loginRequest; } swagger測(cè)試，沒(méi)什么好貼圖的，就省了吧。。
-
4.傳送門
BB兩句
為啥總感覺(jué)swagger3變丑了好多。。。
作者：Echo_Ye
WX：Echo_YeZ
email ：echo_yezi@qq.com
個(gè)人站點(diǎn)：在搭了在搭了。。。（右鍵 - 新建文件夾）
