Swagger實現接口版本號管理
前言：使用swagger暴露對外接口時原則是每個系統在不同的迭代版本僅僅需要暴露該迭代版本的接口給外部使用，客戶端不需要關心不相關的接口
先來看張效果圖
下面是實現代碼：
定義注解ApiVersion：
|
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
|
/** * 接口版本管理注解 * @author 周寧 * @Date 2018-08-30 11:48 */@Retention(RetentionPolicy.RUNTIME)@Target(ElementType.METHOD)public @interface ApiVersion { /** * 接口版本號(對應swagger中的group) * @return String[] */ String[] group(); } |
定義一個用于版本常量的類ApiVersionConstant
|
1
2
3
4
5
6
7
8
9
10
11
12
|
/** * api版本號常量類 * @author 周寧 * @Date 2018-08-30 13:30 */public interface ApiVersionConstant { /** * 圖審系統手機app1.0.0版本 */ String FAP_APP100 = "app1.0.0"; } |
更改SwaggerConfig添加Docket(可以理解成一組swagger 接口的集合)，并定義groupName,根據ApiVersion的group方法區分不同組(迭代)的接口，代碼如下：
|
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
40
41
42
|
@Configuration@EnableSwagger2@EnableWebMvcpublic class SwaggerConfig { //默認版本的接口api-docs分組 @Bean public Docket vDefault(){ return new Docket(DocumentationType.SWAGGER_2) .apiInfo(buildApiInf()) .select() .apis(RequestHandlerSelectors.basePackage("com.gysoft"))//controller路徑 .paths(PathSelectors.any()) .build(); } //app1.0.0版本對外接口 @Bean public Docket vApp100(){ return new Docket(DocumentationType.SWAGGER_2) .apiInfo(buildApiInf()) .groupName(FAP_APP100) .select() .apis(input -> { ApiVersion apiVersion = input.getHandlerMethod().getMethodAnnotation(ApiVersion.class); if(apiVersion!=null&&Arrays.asList(apiVersion.group()).contains(FAP_APP100)){ return true; } return false; })//controller路徑 .paths(PathSelectors.any()) .build(); } private ApiInfo buildApiInf(){ return new ApiInfoBuilder() .title("接口列表") .termsOfServiceUrl("http://127.0.0.1:8080/swagger-ui.html") .description("springmvc swagger 接口測試") .version("1.0.0") .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
|
/** * @author 周寧 * @Date 2018-08-24 11:05 */@RestController@RequestMapping("/document")@Api(value = "資料文檔或者CAD圖紙", description = "資料文檔或者CAD圖紙")public class DocumentController extends GyBasicSession { private static final Logger logger = LoggerFactory.getLogger(DocumentController.class); @ApiImplicitParams({@ApiImplicitParam(name = "page", value = "當前頁數", dataType = "int", paramType = "path"), @ApiImplicitParam(name = "pageSize", value = "每頁大小", dataType = "int", paramType = "path"), @ApiImplicitParam(name = "projectId", value = "項目id", dataType = "string", paramType = "path"), @ApiImplicitParam(name = "stageNum", value = "階段編號", dataType = "string", paramType = "path"), @ApiImplicitParam(name = "type", value = "0資料(文檔);1cad圖紙", dataType = "int", paramType = "path"), @ApiImplicitParam(name = "searchkey", value = "搜索關鍵字", dataType = "string", paramType = "query")}) @ApiOperation("分頁獲取資料文檔(CAD圖紙)列表數據") @GetMapping("/pageQueryAppDocumentInfo/{page}/{pageSize}/{projectId}/{stageNum}/{type}") @ApiVersion(group = ApiVersionConstant.FAP_APP100) public PageResult<AppDocumentInfo> pageQueryAppDocumentInfo(@PathVariable Integer page, @PathVariable Integer pageSize, @PathVariable String projectId, @PathVariable String stageNum, @PathVariable Integer type, @RequestParam String searchkey) { return null; } } |
使用swagger測試接口
swagger：自動掃描 controller 包下的請求，生成接口文檔，并提供測試功能。
引入依賴
|
1
2
3
4
5
6
7
8
9
10
11
12
|
<!-- https://mvnrepository.com/artifact/io.springfox/springfox-swagger2 --> <dependency> <groupId>io.springfox</groupId> <artifactId>springfox-swagger2</artifactId> <version>2.9.2</version> </dependency> <!-- https://mvnrepository.com/artifact/io.springfox/springfox-swagger-ui --> <dependency> <groupId>io.springfox</groupId> <artifactId>springfox-swagger-ui</artifactId> <version>2.9.2</version> </dependency> |
在 config 包引入 swagger 自定義配置類
|
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
40
41
42
|
package com.zhiyou100.zymusic.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;/** * @author teacher * @date 2019/9/25 */@Configuration@EnableSwagger2public class MySwaggerConfiguration { @Bean public Docket createRestApi() { return new Docket(DocumentationType.SWAGGER_2) .apiInfo(apiInfo()) .select() .apis(RequestHandlerSelectors.any()) .paths(PathSelectors.any()) .build(); } private ApiInfo apiInfo() { return new ApiInfoBuilder() //標題 .title("Spring Boot 中使用 Swagger2 構建 RESTful APIs") //簡介 .description("hello swagger") //服務條款 .termsOfServiceUrl("1. xxx\n2. xxx\n3. xxx") //作者個人信息 .contact(new Contact("admin", "http://www.zhiyou100.com", "admin@zhiyou100.com")) //版本 .version("1.0") .build(); }} |
啟動項目后，使用 http://localhost:8080/swagger-ui.html
選擇需要測試的接口：Try it out -> 填寫參數 -> Execute -> 查看響應
以上為個人經驗，希望能給大家一個參考，也希望大家多多支持服務器之家。
原文鏈接：https://blog.csdn.net/qq_23536449/article/details/89878029
