文章目录
简介
Swagger是一个规范和完整的框架,用于生成、描述、调用和可视化 RESTful 风格的 Web 服务。总体目标是使客户端和文件系统作为服务器以同样的速度来更新。文件的方法,参数和模型紧密集成到服务器端的代码,允许API来始终保持同步。
Spring Boot 整合 Swagger
引入依赖
<!--整合swagger-->
<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>
<!--UI增强-->
<dependency>
<groupId>com.github.xiaoymin</groupId>
<artifactId>swagger-bootstrap-ui</artifactId>
<version>1.9.6</version>
</dependency>
配置 Swagger Ui 主界面基本信息
swagger 配置信息也可以不用配置在 yml 文件中, 可以在配置文件中直接定义。
server:
port: 8763
swagger:
addr: localhost
port: ${server.port}
profiles:
title: 标题
description: 描述
version: 1.0
termsOfServiceUrl: termsOfServiceUrl
license: license
licenseUrl: http://${swagger.addr}:${swagger.port}/doc.html
contact:
name: swagger2
email: xxxxxxxx@163.com
url: http://${swagger.addr}:${swagger.port}/swagger-ui.html}
增加 Swagger 配置类
定义 Swagger 属性配置类,读取 yml 配置中的信息, 同时设置默认值,yml 中配置不存在时取默认值。
@Data
@Component
public class SwaggerProperties {
@Value("${swagger.profiles.title:默认标题}")
private String title;
@Value("${swagger.profiles.description:默认描述}")
private String description;
@Value("${swagger.profiles.version:1.0}")
private String version;
@Value("${swagger.profiles.termsOfServiceUrl:}")
private String termsOfServiceUrl;
@Value("${swagger.profiles.license:}")
private String license;
@Value("${swagger.profiles.licenseUrl:}")
private String licenseUrl;
@Value("${swagger.port:${server.port}}")
private String port;
@Value("${swagger.addr:localhost}")
private String addr;
@Value("${swagger.contact.name:}")
private String contactName;
@Value("${swagger.contact.email:}")
private String contactEmail;
@Value("${swagger.contact.url:}")
private String contactUrl;
}
配置SwaggerApi, 在配置类中添加以下注解
@Configuration
: 标注这是一个配置类
@EnableSwagger2
: 开启Swagger 文档
@EnableSwaggerBootstrapUI
: 开启 Swagger UI 增强
@Configuration
@EnableSwagger2
@EnableSwaggerBootstrapUI
public class SwaggerConfig {
@Autowired
private SwaggerProperties properties;
@Bean
public Docket createRestApi() {
return new Docket(DocumentationType.SWAGGER_2)
//用于生成API信息
.apiInfo(apiInfo())
//select()函数返回一个ApiSelectorBuilder实例,用来控制接口被swagger做成文档
.select()
//用于指定扫描哪个包下的接口
//.apis(RequestHandlerSelectors.withMethodAnnotation(ApiOperation.class))
.apis(RequestHandlerSelectors.basePackage("com.example"))
//选择所有的API,如果你想只为部分API生成文档,可以配置这里
.paths(PathSelectors.any())
.build();
}
/*
*用于定义API主界面的信息,比如可以声明所有的API的总标题、描述、版本
*/
private ApiInfo apiInfo() {
return new ApiInfoBuilder()
//用来自定义API的标题
.title(properties.getTitle())
//用来描述整体的API
.description(properties.getDescription())
//可以用来定义版本
.version(properties.getVersion())
//用于定义服务的域名
.termsOfServiceUrl(properties.getTermsOfServiceUrl())
.license(properties.getLicense())
.licenseUrl(properties.getLicenseUrl())
//创建人信息
.contact(new Contact(
properties.getContactName(),
String.format(properties.getContactUrl()),
properties.getContactEmail()
))
.build();
}
}
访问 Swagger 文档
默认访问地址: http://localhost:port/swagger-ui.html
UI增强后访问地址: http://localhost:port/doc.html
常用注解
-
@ApiIgnore
忽略添加了该注解的方法或类,使其不在文档页面进行展示。作用在控制器类
忽略被该注解标注的控制器的所有方法,使其不在文档页面进行展示。作用在属性
忽略被该注解标注的属性,使其不在文档页面进行展示。作用在方法
忽略被该注解标注的方法, 使其不展示在文档界面, 例如:
@Api(tags = "swagger 控制器1")
@RestController
@RequestMapping("swagger")
public class SwaggerController {
@PostMapping("testSwagger1")
@ApiOperation(value = "Swagger 测试接口1", httpMethod = "POST", notes = "Swagger测试接口1")
public void test1(){
}
@ApiIgnore
@PostMapping("testSwagger2")
@ApiOperation(value = "Swagger 测试接口2", httpMethod = "POST", notes = "Swagger测试接口2")
public void test2(){
}
}
如下所示,【Swagger测试接口2】 由于被@ApiIgnore
标注,故而不展示在文档页,文档中只能看到 【Swagger测试接口1】
-
@Api
用在类上,该注解将一个Controller(Class)标注为一个swagger资源(API)。在默认情况下,Swagger-Core只会扫描解析具有@Api
注解的类,而会自动忽略其他类别资源(JAX-RS endpoints,Servlets等等)的注解。该注解包含以下几个重要属性- tags:API分组标签。具有相同标签的API将会被归并在一组内展示。
- value:如果tags没有定义,value将作为Api的tags使用
- description:API的详细描述
usage:
@Api(tags = “swagger 控制器1” , description = “这是swagger控制器”) -
@ApiOperation
在指定的(路由)路径上,对一个操作或HTTP方法进行描述。具有相同路径的不同操作会被归组为同一个操作对象。不同的HTTP请求方法及路径组合构成一个唯一操作。此注解的属性有:- value: 对操作的简单说明,长度为120个字母,60个汉字。
- notes: 对操作的详细说明。
- httpMethod: HTTP请求的动作名,可选值有:“GET”, “HEAD”, “POST”, “PUT”, “DELETE”, “OPTIONS” , “PATCH”。
- code: 默认为200,有效值必须符合标准的HTTP Status Code Definitions。
usage:
@ApiOperation(value = “Swagger 测试接口1”, httpMethod = “POST”, notes = “Swagger测试接口1”) -
@ApiParam
增加对参数的元信息说明。可与@ApiModel
配合使用。其主要的属性有- required: 是否必传,默认为false
- value: 参数说明
-
@ApiModel
描述一个Model的信息(一般用在请求参数无法使用@ApiImplicitParam注解进行描述的时候)
提供对Swagger model额外信息的描述。在标注@ApiOperation注解的操作内,所有的类将自动被内省(introspected),但利用这个注解可以做一些更加详细的model结构说明。主要属性有:- value: model的别名,默认为类名
- description: model的详细描述
-
@ApiModelProperty
描述一个model的属性, 对model属性的注解,主要的属性值有:- value: 属性描述
- example: 属性的示例值
- required: 是否为必须值
使用示例:
@Data
@ApiModel(value = "测试实体", description = "测试实体描述")
public class TestDto {
@ApiModelProperty(name = "名字", required = false, example = "张三")
private String name;
@ApiModelProperty(name = "编码", required = false, example = "001")
private String code;
}
-
@ApiImplicitParams
用在方法上,注解ApiImplicitParam的容器类,以数组方式存储。 -
@ApiImplicitParam
对API的单一参数进行注解。虽然注解@ApiParam同JAX-RS参数相绑定,但这个@ApiImplicitParam注解可以以统一的方式定义参数列表,也是在Servelet及非JAX-RS环境下,唯一的方式参数定义方式。注意这个注解@ApiImplicitParam必须被包含在注解@ApiImplicitParams之内。可以设置以下参数属性:- name: 参数名称
- value: 参数描述
- required: 是否必传
- dataType: 参数类型,可以为类名,也可以为基本类型(String,int、boolean等)
- paramType: 参数的传入(请求)类型,可选的值有path, query, body, header , form。
usage:
@ApiImplicitParams({ @ApiImplicitParam(name = "id", value = "唯一标识符", required = true, paramType = "form", dataType = "String"), })
-
@ApiResponses
注解@ApiResponse的包装类,数组结构。即使需要使用一个@ApiResponse注解,也需要将
@ApiResponse注解包含在注解@ApiResponses内。 -
@ApiResponse
描述一个操作可能的返回结果。当REST API请求发生时,这个注解可用于描述所有可能的成功与错误码。可以用,也可以不用这个注解去描述操作的返回类型,但成功操作的返回类型必须在@ApiOperation中定义。如果API具有不同的返回类型,那么需要分别定义返回值,并将返回类型进行关联。但Swagger不支持同一返回码,多种返回类型的注解。注意:这个注解必须被包含在@ApiResponses注解中。- code: HTTP请求返回码。有效值必须符合标准的HTTP Status Code Definitions。
- message: 更加易于理解的文本消息
- response: 返回类型信息,必须使用完全限定类名,比如“com.xyz.cc.Person.class”。
- responseContainer: 如果返回类型为容器类型,可以设置相应的值。有效值为 “List”, “Set” ,“Map”,其他任何无效的值都会被忽略。
注解使用案例
1、@ApiImplicitParams
和 @ApiResponse
一般是配合 @GetMapping
使用。
2、同一接口有多种返回格式时,可以使用 @ApiResponses
和 @ApiResponse
使用不同的返回码返回不同的结果,如下 ”Swagger 测试GET接口“ 所示。
3、@ApiParam
和 @ApiModel
可以搭配使用, 如下 ”Swagger 测试POST接口“所示。
@Api(tags = "swagger 控制器2", description = "这是swagger控制器2")
@RestController
@RequestMapping("swagger2")
public class SwaggerController2 {
@GetMapping("testGet")
@ApiOperation(value = "Swagger 测试GET接口", httpMethod = "GET", notes = "Swagger测试GET接口")
@ApiImplicitParams({
@ApiImplicitParam(name = "id", value = "id", required = false, paramType = "form", dataType = "String"),
@ApiImplicitParam(name = "name", value = "名称", required = false, paramType = "form", dataType = "String"),
})
@ApiResponses({
@ApiResponse(code = 200,message = "响应1",response = TestDto.class),
@ApiResponse(code = 201,message = "响应2",response = Test2Dto.class),
})
public CommonResult testGet(@RequestParam(name = "id", required = false, defaultValue = "1") String id
, @RequestParam(name = "name", required = false, defaultValue = "1") Integer name) {
return new CommonResult(new TestDto());
}
@PostMapping("testPost")
@ApiOperation(value = "Swagger 测试POST接口", httpMethod = "GET", notes = "Swagger测试POST接口")
public CommonResult<TestDto> testPost(@ApiParam @RequestBody TestDto params){
return new CommonResult<>(new TestDto());
}
}
Swagger 分组
Swagger 分组通过 Docket.groupName() 方法来区分实现
方式一:静态配置
通过在配置类中注入多个bean来实现, 不同的bean 扫描不同包下的方法。
@Configuration
@EnableSwagger2
@EnableSwaggerBootstrapUI
public class SwaggerConfig {
@Autowired
private SwaggerProperties properties;
/*
*用于定义API主界面的信息,比如可以声明所有的API的总标题、描述、版本
*/
private ApiInfo apiInfo() {
return new ApiInfoBuilder()
//用来自定义API的标题
.title(properties.getTitle())
//用来描述整体的API
.description(properties.getDescription())
//可以用来定义版本
.version(properties.getVersion())
//用于定义服务的域名
.termsOfServiceUrl(properties.getTermsOfServiceUrl())
.license(properties.getLicense())
.licenseUrl(properties.getLicenseUrl())
//创建人信息
.contact(new Contact(
properties.getContactName(),
String.format(properties.getContactUrl()),
properties.getContactEmail()
))
.build();
}
@Bean("defaultApi")
public Docket defaultApi() {
return new Docket(DocumentationType.SWAGGER_2)
//用于生成API信息
.apiInfo(apiInfo())
//配置不同的分组
.groupName("defaultGroup")
//select()函数返回一个ApiSelectorBuilder实例,用来控制接口被swagger做成文档
.select()
//用于指定扫描哪个包下的接口
.apis(RequestHandlerSelectors.basePackage("com.example"))
//选择所有的API,如果你想只为部分API生成文档,可以配置这里
.paths(PathSelectors.any())
.build();
}
@Bean("testApi")
public Docket testApi() {
return new Docket(DocumentationType.SWAGGER_2)
//用于生成API信息
.apiInfo(apiInfo())
//配置不同的分组
.groupName("testGroup")
//select()函数返回一个ApiSelectorBuilder实例,用来控制接口被swagger做成文档
.select()
//用于指定扫描哪个包下的接口
.apis(RequestHandlerSelectors.basePackage("com.example"))
//选择所有的API,如果你想只为部分API生成文档,可以配置这里
.paths(PathSelectors.any())
.build();
}
}
方式二:动态配置
通过自定义注解,来实现接口的动态分组
定义枚举类,配置分组的文档显示分组名以及bean实例id
/**
* Swagger接口文档分组枚举
*/
@Getter
@AllArgsConstructor
public enum ApiGroupEnum {
DEFAULT("default", "Default", "defaultDocket"),
TEST("test", "测试接口", "testDocket"),
;
public String groupKey;
public String groupName;
//unique
public String beanName;
}
自定义注解,通过在控制器中添加该注解,实现 API 的动态分组
/**
* Swagger接口文档分组注解
* <pre>
* 在Controller类上添加该注解,在注解中指定所属分组。
* </pre>
*/
@Retention(RetentionPolicy.RUNTIME)
@Target(ElementType.TYPE)
public @interface ApiGroup {
ApiGroupEnum[] group() default ApiGroupEnum.DEFAULT;
}
Swagger 配置辅助类,包含一系列配置 Swagger 的方法, 包括动态配置分组的方法。
/**
* Swagger配置辅助方法基础类
*/
public abstract class SwaggerConfigHelper {
@Autowired
private SwaggerProperties properties;
@Autowired
ApplicationContext applicationContext;
/**
* 根据枚举类创建Docket, ApiGroupEnum
*
* @param applicationContext
* @return
*/
public void buildDocket(ApplicationContext applicationContext) {
DefaultListableBeanFactory beanFactory = (DefaultListableBeanFactory) applicationContext.getAutowireCapableBeanFactory();
for (ApiGroupEnum apiGroupEnum : ApiGroupEnum.values()) {
beanFactory.registerSingleton(apiGroupEnum.getBeanName(), buildProductApi(apiGroupEnum.getGroupName(), apiGroupEnum.getGroupKey()));
}
}
/**
* 根据分组构建完整的API注册信息
*
* @param apiGroupName
* @param apiGroupKey
* @return
*/
public Docket buildProductApi(String apiGroupName, String apiGroupKey) {
Docket docket = buildDocket(apiGroupName)
.apiInfo(buildBaseProductApiInfo());
ApiSelectorBuilder builder = buildApiForGroupKey(docket, apiGroupKey);
return buildApiSecurityAuth(builder);
}
/*
*根据分组名创建Docket
*/
public Docket buildDocket(String apiGroupName) {
return new Docket(DocumentationType.SWAGGER_2)
.groupName(apiGroupName)
.useDefaultResponseMessages(false)
.forCodeGeneration(false);
}
/*
*用于定义API主界面的信息,比如可以声明所有的API的总标题、描述、版本
*/
protected ApiInfo buildBaseProductApiInfo() {
Contact contact = new Contact(properties.getContactName(), properties.getContactUrl(), properties.getContactEmail());
return buildApiInfo(properties.getTitle(), properties.getDescription(), properties.getVersion(), properties.getTermsOfServiceUrl(), contact);
}
@SuppressWarnings("rawtypes")
protected ApiInfo buildApiInfo(String title, String description, String version, String url, Contact contact) {
return new ApiInfoBuilder()
.title(title)
.description(description)
.version(version)
.termsOfServiceUrl(url)
.contact(contact)
.license(properties.getLicense())
.licenseUrl(properties.getLicenseUrl())
.extensions(new ArrayList<VendorExtension>())
.build();
}
/*
* 根据分组key对API进行注册
*/
public ApiSelectorBuilder buildApiForGroupKey(Docket docket, String apiGroupKey) {
return docket.select()
.apis(getPredicateWithGroup(apiGroupKey))
.paths(PathSelectors.any());
}
/*
* 通过接口分组过滤
*/
protected Predicate<RequestHandler> getPredicateWithGroup(String group) {
return new Predicate<RequestHandler>() {
@Override
public boolean apply(RequestHandler input) {
// 找到controller类上的ApiGroup注解
Optional<ApiGroup> apiGroup = input.findControllerAnnotation(ApiGroup.class);
if (apiGroup.isPresent() && Arrays.asList(apiGroup.get().group()).contains(ApiGroupEnum.valueOf(group.toUpperCase()))) {
return true;
}
return false;
}
};
}
/*
* 构建API安全认证
*/
public Docket buildApiSecurityAuth(ApiSelectorBuilder builder) {
return builder.build().securityContexts(Lists.newArrayList(buildSecurityContext()))
.securitySchemes(Lists.newArrayList(apiSecurityKey()));
}
private SecurityContext buildSecurityContext() {
return SecurityContext.builder()
.securityReferences(defaultAuth())
.forPaths(PathSelectors.regex("/.*"))
.build();
}
/*
* 默认的认证方式
*/
private List<SecurityReference> defaultAuth() {
AuthorizationScope authorizationScope = new AuthorizationScope("global", "accessEverything");
AuthorizationScope[] authorizationScopes = new AuthorizationScope[1];
authorizationScopes[0] = authorizationScope;
return Lists.newArrayList(new SecurityReference("BearerToken", authorizationScopes));
}
private ApiKey apiSecurityKey() {
return new ApiKey("BearerToken", "Authorization", "header");
}
/*
* 根据包名对API进行注册
*/
public ApiSelectorBuilder buildApiForPackage(Docket docket, String basePackage) {
return docket.select()
.apis(RequestHandlerSelectors.basePackage(basePackage))
.paths(PathSelectors.any());
}
}
编写配置类, 根据枚举类创建 API 分组。
@Configuration
@EnableSwagger2
@EnableSwaggerBootstrapUI
public class SwaggerConfig1 extends SwaggerConfigHelper{
@PostConstruct
public void buildDocket() {
buildDocket(applicationContext);
}
}
分组查询
访问 /swagger-resources
, 查看分组信息,如访问 http://localhost:8763/swagger-resources
接口返回
[{
"name": "defaultGroup",
"url": "/v2/api-docs?group=defaultGroup",
"swaggerVersion": "2.0",
"location": "/v2/api-docs?group=defaultGroup"
}, {
"name": "testGroup",
"url": "/v2/api-docs?group=testGroup",
"swaggerVersion": "2.0",
"location": "/v2/api-docs?group=testGroup"
}]
注解使用及页面效果
在控制器添加自定义注解@ApiGroup
, group 属性可以填写多个,也可以不填,如果不填归入默认分组。
@ApiGroup(group = {ApiGroupEnum.DEFAULT, ApiGroupEnum.TEST})
@Api(tags = "swagger 控制器2", description = "这是swagger控制器2")
@RestController
@RequestMapping("swagger2")
public class SwaggerController2 {
@GetMapping("testGet")
@ApiOperation(value = "Swagger 测试GET接口", httpMethod = "GET", notes = "Swagger测试GET接口")
@ApiImplicitParams({
@ApiImplicitParam(name = "id", value = "id", required = false, paramType = "form", dataType = "String"),
@ApiImplicitParam(name = "name", value = "名称", required = false, paramType = "form", dataType = "String"),
})
@ApiResponses({
@ApiResponse(code = 200,message = "响应1",response = TestDto.class),
@ApiResponse(code = 201,message = "响应2",response = Test2Dto.class),
})
public CommonResult testGet(@RequestParam(name = "id", required = false, defaultValue = "1") String id
, @RequestParam(name = "name", required = false, defaultValue = "1") Integer name) {
return new CommonResult(new TestDto());
}
@PostMapping("testPost")
@ApiOperation(value = "Swagger 测试POST接口", httpMethod = "GET", notes = "Swagger测试POST接口")
public CommonResult<TestDto> testPost(@ApiParam @RequestBody TestDto params){
return new CommonResult<>(new TestDto());
}
}
效果展示
@ApiGroup(group = {ApiGroupEnum.DEFAULT, ApiGroupEnum.TEST}), group 属性配置了两个分组, 所以页面切换任意一个分组都可以看到 “swagger 控制器2”
Swagger 安全
为了文档安全性考虑,可以添加用户认证, 添加后 Swagger 文档需要输入用户认证信息才能访问。还可以通过@Profile
注解限制访问环境。
添加用户认证配置
swagger:
production: false
basic:
enable: true
username: user
password: 123456
重新启动,访问文档地址会跳出用户认证界面如下所示
通过@Profile
注解控制访问环境
添加配置
spring:
profiles:
active: dev
控制器添加注解, 声明开发环境可访问。@Profile
注解可声明多个环境,以逗号分隔。如: @Profile({"dev", "prod"})
@Configuration
@EnableSwagger2
@EnableSwaggerBootstrapUI
@Profile({"dev"})
public class SwaggerConfig1 extends SwaggerConfigHelper{
@PostConstruct
public void buildDocket() {
buildDocket(applicationContext);
}
}
可能存在的问题
1、Failed to start bean ‘documentationPluginsBootstrapper’
高版本Spring Boot 整合 Swagger 时可能报错 Failed to start bean ‘documentationPluginsBootstrapper’ , 报错信息如下:
org.springframework.context.ApplicationContextException: Failed to start bean 'documentationPluginsBootstrapper'; nested exception is java.lang.NullPointerException
方案一 : 增加配置属性
Springfox使用的路径匹配是基于AntPathMatcher的, 而Spring Boot 2.6.X使用的是PathPatternMatcher, 所以我们需要添加AntPathMatcher配置。
spring:
mvc:
pathmatch:
matching-strategy: ant_path_matcher
方案二: 增加配置类
添加 WebMvcConfig 配置类, 继承 WebMvcConfigurationSupport 类, 重写 addResourceHandlers()方法。
import org.springframework.context.annotation.Configuration;
import org.springframework.web.servlet.config.annotation.ResourceHandlerRegistry;
import org.springframework.web.servlet.config.annotation.WebMvcConfigurationSupport;
@Configuration
public class WebMvcConfig extends WebMvcConfigurationSupport {
@Override
public void addResourceHandlers(ResourceHandlerRegistry registry) {
registry.addResourceHandler("/**")
.addResourceLocations("classpath:/static/");
registry.addResourceHandler("swagger-ui.html", "doc.html")
.addResourceLocations("classpath:/META-INF/resources/");
registry.addResourceHandler("/webjars/**")
.addResourceLocations("classpath:/META-INF/resources/webjars/");
}
}