swagger是一個不錯的接口生成工具，而且其UI界面可以查看以及測試接口。
之前前后端分離的時候是將文檔寫在docx中，然后自己測試用postman進行測試。確實比較浪費時間。
1.簡單的整合
0.pom新增
<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.增加配置文件：
package com.zd.bx.config.swapper2; import org.springframework.boot.autoconfigure.condition.ConditionalOnProperty; import org.springframework.context.annotation.Bean; import org.springframework.context.annotation.Configuration; import org.springframework.web.servlet.config.annotation.ResourceHandlerRegistry; import org.springframework.web.servlet.config.annotation.WebMvcConfigurer; 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; @Configuration @EnableSwagger2 // 是否開啟swagger，正式環境一般是需要關閉的（避免不必要的漏洞暴露！），可根據springboot的多環境配置進行設置 @ConditionalOnProperty(name = "swagger.enable", havingValue = "true") public class Swagger2Configure implements WebMvcConfigurer { // swagger2的配置文件，這里可以配置swagger2的一些基本的內容，比如掃描的包等等 @Bean public Docket createRestApi() { return new Docket(DocumentationType.SWAGGER_2).apiInfo(apiInfo()).select() // 為當前包路徑 .apis(RequestHandlerSelectors.basePackage("com.zd.bx.controller")).paths(PathSelectors.any()).build(); } // 構建 api文檔的詳細信息函數,注意這里的注解引用的是哪個 private ApiInfo apiInfo() { return new ApiInfoBuilder() // 頁面標題 .title("XXX軟件接口描述") // 創建人信息 .contact(new Contact("張三", "https://www.baidu.com/", "zhangsan@qq.com")) // 版本號 .version("1.0") // 描述 .description("API 描述").build(); } @Override public void addResourceHandlers(ResourceHandlerRegistry registry) { registry.addResourceHandler("swagger-ui.html").addResourceLocations("classpath:/META-INF/resources/"); registry.addResourceHandler("/webjars/**").addResourceLocations("classpath:/META-INF/resources/webjars/"); } }
2.application.properties激活swagger2
#是否激活 swagger true or false swagger.enable=true
如果有攔截器或者權限過濾器需要放行swagger相關請求：
例如我的shiro權限配置如下：
FILTER_CHAIN_DEFINITION_MAP.put("/swagger-ui.html", "anon"); // swagger放開
FILTER_CHAIN_DEFINITION_MAP.put("/webjars/**", "anon"); // swagger請求的資源放開
FILTER_CHAIN_DEFINITION_MAP.put("/swagger-resources/**", "anon"); // swagger請求的資源放開
FILTER_CHAIN_DEFINITION_MAP.put("/v2/api-docs/**", "anon"); // swagger請求的資源放開
3. 啟動應用訪問：
2.注解使用
1.@Api 修飾類
// tags:說明該類的作用，可以在UI界面上看到的注解,value=該參數沒什么意義、在UI界面上也看到 @Api(tags = { "用戶接口" }) public class UserController extends AbstractController<User, Long> {
如下：
2.@ApiOperation 方法描述
3.@ApiResponses、@ApiResponse修飾返回值信息
4.@ApiImplicitParam 參數描述
5.@ApiModel、@ApiModelProperty 修飾請求的參數和返回參數的信息(用於JSON請求參數和返回值)
例如：
@GetMapping("/detail/{id}")
// 方法描述
@ApiOperation(value = "詳情", notes = "查詢詳情")
// 返回信息描述
@ApiResponses({ @ApiResponse(code = -1, message = "請求正確") })
// 參數描述
@ApiImplicitParam(name = "id", value = "請求的ID", required = true)
public JSONResultUtil<T> detail(@PathVariable() E id, HttpServletRequest request) {
T bean = getBaseService().selectById(id);
ValidateUtils.isTrue(bean != null, "u100003");
return JSONResultUtil.successWithMsgAndData("ok", bean);
}
結果：
3. 如果希望在用UI請求的時候攜帶參數，比如cookie、header等參數
package com.zd.bx.config.swapper2; import java.util.ArrayList; import java.util.List; import org.springframework.boot.autoconfigure.condition.ConditionalOnProperty; import org.springframework.context.annotation.Bean; import org.springframework.context.annotation.Configuration; import org.springframework.web.servlet.config.annotation.ResourceHandlerRegistry; import org.springframework.web.servlet.config.annotation.WebMvcConfigurer; import com.zd.bx.utils.constant.DefaultValue; import springfox.documentation.builders.ApiInfoBuilder; import springfox.documentation.builders.ParameterBuilder; import springfox.documentation.builders.PathSelectors; import springfox.documentation.builders.RequestHandlerSelectors; import springfox.documentation.schema.ModelRef; import springfox.documentation.service.ApiInfo; import springfox.documentation.service.Contact; import springfox.documentation.service.Parameter; import springfox.documentation.spi.DocumentationType; import springfox.documentation.spring.web.plugins.Docket; import springfox.documentation.swagger2.annotations.EnableSwagger2; @Configuration @EnableSwagger2 // 是否開啟swagger，正式環境一般是需要關閉的（避免不必要的漏洞暴露！），可根據springboot的多環境配置進行設置 @ConditionalOnProperty(name = "swagger.enable", havingValue = "true") public class Swagger2Configure implements WebMvcConfigurer { // swagger2的配置文件，這里可以配置swagger2的一些基本的內容，比如掃描的包等等 @Bean public Docket createRestApi() { // 增加請求頭配置 ParameterBuilder params = new ParameterBuilder(); List<Parameter> pars = new ArrayList<Parameter>(); // 設置參數的名字以及類型：可以是cookie、header等信息 Parameter access_token = new ParameterBuilder().name(DefaultValue.TOKEN_KEY).description("access_token") .modelRef(new ModelRef("string")).parameterType("header").required(false).build(); Parameter belong_database = new ParameterBuilder().name(DefaultValue.DATABASE_NAME_KEY) .description("belong_database").modelRef(new ModelRef("string")).parameterType("header").required(false) .build(); pars.add(access_token); pars.add(belong_database); return new Docket(DocumentationType.SWAGGER_2).apiInfo(apiInfo()).select() .apis(RequestHandlerSelectors.basePackage("com.zd.bx.controller")).paths(PathSelectors.any()).build() .globalOperationParameters(pars); } private ApiInfo apiInfo() { return new ApiInfoBuilder() // 頁面標題 .title("XXX軟件接口描述") // 創建人信息 .contact(new Contact("張三", "https://www.baidu.com/", "zhangsan@qq.com")) // 版本號 .version("1.0") // 描述 .description("API 描述").build(); } @Override public void addResourceHandlers(ResourceHandlerRegistry registry) { registry.addResourceHandler("swagger-ui.html").addResourceLocations("classpath:/META-INF/resources/"); registry.addResourceHandler("/webjars/**").addResourceLocations("classpath:/META-INF/resources/webjars/"); } }
結果：
補充：swagger2生成所有類型的請求文檔，如下：
原因是我們沒有指定請求方式，也就是 @RequestMapping 沒有指定methos。解決辦法：直接用@PostMapping或者指定method。
補充：swagger2也可以對指定的包或者包含某注解的類進行生成API
@Bean public Docket createRestApi() { // 增加請求頭配置 ParameterBuilder params = new ParameterBuilder(); List<Parameter> pars = new ArrayList<Parameter>(); // 設置參數的名字以及類型：可以是cookie、header等信息 Parameter access_token = new ParameterBuilder().name(DefaultValue.TOKEN_KEY).description("access_token") .modelRef(new ModelRef("string")).parameterType("header").required(false).build(); Parameter belong_database = new ParameterBuilder().name(DefaultValue.DATABASE_NAME_KEY) .description("belong_database").modelRef(new ModelRef("string")).parameterType("header").required(false) .build(); pars.add(access_token); pars.add(belong_database); return new Docket(DocumentationType.SWAGGER_2).apiInfo(apiInfo()).select() // 為任何接口生成API文檔 .apis(RequestHandlerSelectors.any()) // 指定包生成API文檔 // .apis(RequestHandlerSelectors.basePackage("com.zd.bx.controller")) // 為有@ApiOperation注解的方法生成API文檔 // .apis(RequestHandlerSelectors.withMethodAnnotation(ApiOperation.class)) // 為有@Api注解的Controller生成API文檔 // .apis(RequestHandlerSelectors.withClassAnnotation(Api.class)) .paths(PathSelectors.any()).build().globalOperationParameters(pars); }
補充： @ApiIgnore用於忽略參數
@GetMapping("test")
public String test(@ApiIgnore String param1, @RequestParam("param2") String param2) {
return param2;
}
結果：
補充：swagger也可以分組。這個在一個項目中Controller特別多的時候比較有用。
package com.xm.ggn.config; import org.springframework.boot.autoconfigure.condition.ConditionalOnProperty; import org.springframework.context.annotation.Bean; import org.springframework.context.annotation.Configuration; import org.springframework.web.servlet.config.annotation.ResourceHandlerRegistry; import org.springframework.web.servlet.config.annotation.WebMvcConfigurer; 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: qlq * @Description * @Date: 17:10 2021/1/30 */ @Configuration @EnableSwagger2 // 是否開啟swagger，正式環境一般是需要關閉的（避免不必要的漏洞暴露！），可根據springboot的多環境配置進行設置 @ConditionalOnProperty(name = "swagger.enable", havingValue = "true") // 按環境區分 //@Profile("dev") public class Swagger2Configure implements WebMvcConfigurer { //根據包進行分組 @Bean public Docket createCommonApi() { return new Docket(DocumentationType.SWAGGER_2).apiInfo(apiInfo()).select() // 為當前包路徑 .apis(RequestHandlerSelectors.basePackage("com.xm.ggn.controller.common")).paths(PathSelectors.any()).build().groupName("common 基礎服務"); } // swagger2的配置文件，這里可以配置swagger2的一些基本的內容，比如掃描的包等等 @Bean public Docket createUserApi() { return new Docket(DocumentationType.SWAGGER_2).apiInfo(apiInfo()).select() // 為當前包路徑 .apis(RequestHandlerSelectors.basePackage("com.xm.ggn.controller.user")).paths(PathSelectors.any()).build().groupName("user 服務"); } // 構建 api文檔的詳細信息函數,注意這里的注解引用的是哪個 private ApiInfo apiInfo() { return new ApiInfoBuilder() // 頁面標題 .title("XXX軟件接口描述") // 創建人信息 .contact(new Contact("張三", "https://www.baidu.com/", "zhangsan@qq.com")) // 版本號 .version("1.0") // 描述 .description("API 描述").build(); } @Override public void addResourceHandlers(ResourceHandlerRegistry registry) { registry.addResourceHandler("swagger-ui.html").addResourceLocations("classpath:/META-INF/resources/"); registry.addResourceHandler("/webjars/**").addResourceLocations("classpath:/META-INF/resources/webjars/"); } }
結果：
補充：如下一個接口
1. 相關Bean
package cn.xm.controller; import io.swagger.annotations.ApiModel; import io.swagger.annotations.ApiModelProperty; import lombok.Data; import java.util.List; @Data @ApiModel("請求實體") public class RequestVO { @ApiModelProperty("序列號req") private String sequenceNum; @ApiModelProperty("用戶集合req") private List<UserVO> userVOS; @Data @ApiModel("UserVO請求實體") public static class UserVO { @ApiModelProperty("用戶名req") private String username; } }
Response：
package cn.xm.controller; import io.swagger.annotations.ApiModel; import io.swagger.annotations.ApiModelProperty; import lombok.Data; import java.util.List; @Data @ApiModel("返回實體") public class ResponseVO { @ApiModelProperty("序列號") private String sequenceNum; @ApiModelProperty("用戶集合") private List<UserVO> userVOS; @Data @ApiModel("UserVO返回實體") public static class UserVO { @ApiModelProperty("用戶名") private String username; } }
2. Controller
package cn.xm.controller; import io.swagger.annotations.Api; import io.swagger.annotations.ApiOperation; import io.swagger.annotations.ApiParam; import org.springframework.stereotype.Controller; import org.springframework.web.bind.annotation.PostMapping; import org.springframework.web.bind.annotation.RequestBody; import org.springframework.web.bind.annotation.RequestMapping; import org.springframework.web.bind.annotation.ResponseBody; import springfox.documentation.annotations.ApiIgnore; @RequestMapping("test2") @Controller("testController2") @Api(tags = "測試接口") public class TestController { @PostMapping("/testSwagger") @ApiOperation("測試swagger接口方法") public ResponseVO test(@RequestBody @ApiParam("請求參數") RequestVO requestVO, @ApiParam("請求參數2") String param2, @ApiIgnore String param3) { return new ResponseVO(); } @PostMapping("/test2") @ApiOperation("測試swagger接口方法") @ResponseBody public ResponseVO2 test2(@RequestBody @ApiParam("請求參數") ResponseVO2 responseVO2) { System.out.println(responseVO2); return responseVO2; } }
其test方法生成的Swagger如下：
