6. Swagger
6.1 简介
Swagger 是一个规范和完整的框架,用于生成、描述、调用和可视化 RESTful 风格的 Web 服务(https://swagger.io/)。Spring已经将Swagger纳入自身的标准,建立了Spring-swagger项目,现在叫Springfox即可使用Swagger。
主要作用:
-
使得前后端分离开发更加方便,有利于团队协作
-
接口的文档在线自动生成,降低后端开发人员编写接口文档的负担
-
功能测试
主要依赖介绍:
- Swagger-tools:提供各种与Swagger进行集成和交互的工具。例如模式检验、Swagger 1.2文档转换成Swagger 2.0文档等功能
- Swagger-core: 用于Java/Scala的的Swagger实现。与JAX-RS(Jersey、Resteasy、CXF…)、Servlets和Play框架进行集成
- Swagger-js: 用于JavaScript的Swagger实现。Swagger-node-express: Swagger模块,用于node.js的Express web应用框架
- Swagger-ui:一个无依赖的HTML、JS和CSS集合,可以为Swagger兼容API动态生成优雅文档。
- Swagger-codegen:一个模板驱动引擎,通过分析用户Swagger资源声明以各种语言生成客户端代码。
6.2 基本使用
下面是一个简单的在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>
- 创建Swagger配置类
创建一个名为SwaggerConfig的Java类,并添加以下内容:
@Configuration
@EnableSwagger2
public class SwaggerConfig {
/**
* 创建API应用
* apiInfo() 增加API相关信息
* 通过select()函数返回一个ApiSelectorBuilder实例,用来控制哪些接口暴露给Swagger来展现,
* 指定扫描的包路径来定义指定要建立API的目录。
* @return
*/
@Bean
public Docket coreApiConfig(){
return new Docket(DocumentationType.SWAGGER_2)
.apiInfo(adminApiInfo())
.groupName("adminApi")
.select()
.paths(PathSelectors.any())//路径下的接口会暴露给Swagger监控
.build();
}
private ApiInfo adminApiInfo(){
return new ApiInfoBuilder()
.title("api文档")
.description("接口描述")
.version("1.0")
.contact(new Contact("","",""))
.build();
}
}
这个类使用了@Configuration注解,表示这是一个配置类。@EnableSwagger2注解开启了Swagger的支持。Docket是Swagger的主要配置类,它定义了API的详细信息,包括标题、描述和版本等信息。
- 添加Swagger注解
在控制器类或控制器方法上添加Swagger注解,例如:
@RestController
@RequestMapping("/api")
@Api(value = "API", tags = { "API" })
public class ApiController {
@GetMapping("/user")
@ApiOperation(value = "save user", notes = "save a user")
public String save() {
return "save a user success!";
}
}
@Api注解表示这是一个API类,value属性表示API的名称,tags属性表示API的标签。
@ApiOperation注解表示这是一个API操作,value属性表示操作的名称,notes属性表示操作的描述。
- 运行应用程序并访问Swagger UI
启动应用程序并在浏览器中访问以下URL:
http://localhost:8080/swagger-ui.html
这将打开Swagger UI,您可以在其中查看你的API文档并测试API。
[外链图片转存失败,源站可能有防盗链机制,建议将图片保存下来直接上传(img-9462mYHA-1688556459158)(C:\Users\昭晞\Desktop\QQ截图20230705192545.png)]
6.3 Swagger常见注解
以下是Swagger常见注解的参数说明及例子:
- @Api
@Api是用于描述整个API的信息,包括API的名称、描述、作者等信息。它可以用在类上。
参数说明:
- value:API的名称。
- tags:API的标签,用于对API进行分类。
示例:
@RestController
@RequestMapping("/api")
@Api(value = "API", tags = { "API" })
public class ApiController {
// ...
}
- @ApiOperation
@ApiOperation是用于描述API的操作,包括操作名称、描述、参数信息等。它可以用在方法上。
参数说明:
- value:操作名称。
- notes:操作描述。
- response:响应类型。
示例:
@GetMapping("/hello")
@ApiOperation(value = "save user", notes = "save a user")
public String save() {
return "save a user success";
}
- @ApiParam
@ApiParam是用于描述API的参数信息,包括参数名称、描述、是否必填等信息。它可以用在方法的参数上。
参数说明:
- value:参数名称。
- required:是否必填。
- defaultValue:参数的默认值。
- allowableValues:参数的可选值。
- example:参数的示例值。
示例:
@PostMapping("/user")
@ApiOperation(value = "Create user", notes = "Create a new user")
public ResponseEntity<User> createUser(
@ApiParam(value = "User object", required = true) @RequestBody User user) {
// ...
}
- @ApiModel
@ApiModel是用于描述数据模型,包括模型名称、描述、属性等信息。它可以用在类上。
参数说明:
- value:模型名称。
- description:模型描述。
示例:
@ApiModel(description = "User object")
public class User {
@ApiModelProperty(value = "User ID", required = true)
private Long id;
@ApiModelProperty(value = "User name", required = true)
private String name;
// ...
}
- @ApiModelProperty
@ApiModelProperty是用于描述数据模型的属性,包括属性名称、描述、是否必填等信息。它可以用在类的属性上。
参数说明:
- value:属性名称。
- required:是否必填。
- defaultValue:属性的默认值。
- allowableValues:属性的可选值。
- example:属性的示例值。
示例:
@ApiModel(description = "User object")
public class User {
@ApiModelProperty(value = "User ID", required = true)
private Long id;
@ApiModelProperty(value = "User name", required = true)
private String name;
// ...
}
- @ApiResponse
@ApiResponse是用于描述API的返回结果,包括返回码、返回信息等信息。它可以用在方法上。
参数说明:
- code:返回码。
- message:返回信息。
- response:响应类型。
示例:
@GetMapping("/user/{id}")
@ApiOperation(value = "Get user by ID", notes = "Get user by ID")
@ApiResponses(value = {
@ApiResponse(code = 200, message = "Success", response = User.class),
@ApiResponse(code = 404, message = "Not found")
})
public ResponseEntity<User> getUserById(
@ApiParam(value = "User ID", required = true) @PathVariable Long id) {
// ...
}
- @ApiResponses
@ApiResponses是用于描述API的多个返回结果,可以包含多个@ApiResponse注解。它可以用在方法上。
参数说明:
- value:返回结果数组。
示例:
@PostMapping("/user")
@ApiOperation(value = "Create user", notes = "Create a new user")
@ApiResponses(value = {
@ApiResponse(code = 201, message = "Created", response = User.class),
@ApiResponse(code = 400, message = "Bad request")
})
public ResponseEntity<User> createUser(
@ApiParam(value = "User object", required = true) @RequestBody User user) {
// ...
}
- @ApiIgnore
@ApiIgnore是用于忽略某个API,可以用在类或方法上。
示例:
@ApiIgnore
@GetMapping("/secret")
public String secret() {
return "Secret API";
}
-
@ApiError :发生错误返回的信息
-
@ApiImplicitParam:一个请求参数
-
@ApiImplicitParams:多个请求参数的描述信息
@ApiImplicitParams:参数说明
属性 | 取值 | 作用 |
---|---|---|
paramType | 查询参数类型 | |
path | 以地址的形式提交数据 | |
query | 直接跟参数完成自动映射赋值 | |
body | 以流的形式提交 仅支持POST | |
header | 参数在request headers 里边提交 | |
form | 以form表单的形式提交 仅支持POST | |
dataType | 参数的数据类型 只作为标志说明,并没有实际验证 | |
Long | ||
String | ||
name | 接收参数名 | |
value | 接收参数的意义描述 | |
required | 参数是否必填 | |
true | 必填 | |
false | 非必填 | |
defaultValue | 默认值 |
6.4 Swagger配置
Swagger常见的配置如下:
@Configuration
@EnableSwagger2//开启Swagger
@ComponentScan(basePackages = { "com.example.demo" })//配置扫描包路径
public class SwaggerConfig {
@Bean
public Docket api() {
return new Docket(DocumentationType.SWAGGER_2)
.apiInfo(apiInfo())//导入api基本说明信息
.select()
.apis(RequestHandlerSelectors.basePackage("com.example.demo"))//基础包路径
.paths(PathSelectors.any("/api/**"))//
.build();
}
//配置Swagger API信息
private ApiInfo apiInfo() {
return new ApiInfoBuilder()
.title("Demo API")//api主题(类似于大标题)
.description("This is a demo API")//描述说明
.version("1.0.0")//版本
.build();//构建ApiInfo对象
}
//配置Swagger安全认证
private ApiKey apiKey() {
return new ApiKey("JWT", "Authorization", "header");//认证方式JWT令牌,
}
//security安全
private SecurityContext securityContext() {
return SecurityContext.builder()
.securityReferences(defaultAuth())
.forPaths(PathSelectors.any())
.build();
}
//authorization批准
private List<SecurityReference> defaultAuth() {//范围
AuthorizationScope authorizationScope = new AuthorizationScope("global", "accessEverything");
AuthorizationScope[] authorizationScopes = new AuthorizationScope[1];
authorizationScopes[0] = authorizationScope;
return Arrays.asList(new SecurityReference("JWT", authorizationScopes));
}
}
6.5 异常
- 大致信息:
org.springframework.context.ApplicationContextException: Failed to start bean ‘documentationPluginsBootstrapper’;
org.springframework.context.ApplicationContextException: Failed to start bean 'documentationPluginsBootstrapper'; nested exception is java.lang.NullPointerException
at org.springframework.context.support.DefaultLifecycleProcessor.doStart(DefaultLifecycleProcessor.java:181) ~[spring-context-5.3.14.jar:5.3.14]
at org.springframework.context.support.DefaultLifecycleProcessor.access$200(DefaultLifecycleProcessor.java:54) ~[spring-context-5.3.14.jar:5.3.14]
at org.springframework.context.support.DefaultLifecycleProcessor$LifecycleGroup.start(DefaultLifecycleProcessor.java:356) ~[spring-context-5.3.14.jar:5.3.14]
at java.lang.Iterable.forEach(Iterable.java:75) ~[na:1.8.0_372]
at org.springframework.context.support.DefaultLifecycleProcessor.startBeans(DefaultLifecycleProcessor.java:155) ~[spring-context-5.3.14.jar:5.3.14]
at org.springframework.context.support.DefaultLifecycleProcessor.onRefresh(DefaultLifecycleProcessor.java:123) ~[spring-context-5.3.14.jar:5.3.14]
at org.springframework.context.support.AbstractApplicationContext.finishRefresh(AbstractApplicationContext.java:935) ~[spring-context-5.3.14.jar:5.3.14]
at org.springframework.context.support.AbstractApplicationContext.refresh(AbstractApplicationContext.java:586) ~[spring-context-5.3.14.jar:5.3.14]
at org.springframework.boot.web.servlet.context.ServletWebServerApplicationContext.refresh(ServletWebServerApplicationContext.java:145) ~[spring-boot-2.6.2.jar:2.6.2]
at org.springframework.boot.SpringApplication.refresh(SpringApplication.java:730) [spring-boot-2.6.2.jar:2.6.2]
at org.springframework.boot.SpringApplication.refreshContext(SpringApplication.java:412) [spring-boot-2.6.2.jar:2.6.2]
at org.springframework.boot.SpringApplication.run(SpringApplication.java:302) [spring-boot-2.6.2.jar:2.6.2]
at org.springframework.boot.SpringApplication.run(SpringApplication.java:1301) [spring-boot-2.6.2.jar:2.6.2]
at org.springframework.boot.SpringApplication.run(SpringApplication.java:1290) [spring-boot-2.6.2.jar:2.6.2]
at com.zhaoxi.swaggertest.SwaggerTestApplication.main(SwaggerTestApplication.java:10) [classes/:na]
Caused by: java.lang.NullPointerException: null
at springfox.documentation.spi.service.contexts.Orderings$8.compare(Orderings.java:112) ~[springfox-spi-2.9.2.jar:null]
at springfox.documentation.spi.service.contexts.Orderings$8.compare(Orderings.java:109) ~[springfox-spi-2.9.2.jar:null]
at com.google.common.collect.ComparatorOrdering.compare(ComparatorOrdering.java:37) ~[guava-20.0.jar:na]
at java.util.TimSort.countRunAndMakeAscending(TimSort.java:355) ~[na:1.8.0_372]
at java.util.TimSort.sort(TimSort.java:220) ~[na:1.8.0_372]
at java.util.Arrays.sort(Arrays.java:1438) ~[na:1.8.0_372]
at com.google.common.collect.Ordering.sortedCopy(Ordering.java:855) ~[guava-20.0.jar:na]
at springfox.documentation.spring.web.plugins.WebMvcRequestHandlerProvider.requestHandlers(WebMvcRequestHandlerProvider.java:57) ~[springfox-spring-web-2.9.2.jar:null]
at springfox.documentation.spring.web.plugins.DocumentationPluginsBootstrapper$2.apply(DocumentationPluginsBootstrapper.java:138) ~[springfox-spring-web-2.9.2.jar:null]
at springfox.documentation.spring.web.plugins.DocumentationPluginsBootstrapper$2.apply(DocumentationPluginsBootstrapper.java:135) ~[springfox-spring-web-2.9.2.jar:null]
at com.google.common.collect.Iterators$7.transform(Iterators.java:750) ~[guava-20.0.jar:na]
at com.google.common.collect.TransformedIterator.next(TransformedIterator.java:47) ~[guava-20.0.jar:na]
at com.google.common.collect.TransformedIterator.next(TransformedIterator.java:47) ~[guava-20.0.jar:na]
at com.google.common.collect.MultitransformedIterator.hasNext(MultitransformedIterator.java:52) ~[guava-20.0.jar:na]
at com.google.common.collect.MultitransformedIterator.hasNext(MultitransformedIterator.java:50) ~[guava-20.0.jar:na]
at com.google.common.collect.ImmutableList.copyOf(ImmutableList.java:249) ~[guava-20.0.jar:na]
at com.google.common.collect.ImmutableList.copyOf(ImmutableList.java:209) ~[guava-20.0.jar:na]
at com.google.common.collect.FluentIterable.toList(FluentIterable.java:614) ~[guava-20.0.jar:na]
at springfox.documentation.spring.web.plugins.DocumentationPluginsBootstrapper.defaultContextBuilder(DocumentationPluginsBootstrapper.java:111) ~[springfox-spring-web-2.9.2.jar:null]
at springfox.documentation.spring.web.plugins.DocumentationPluginsBootstrapper.buildContext(DocumentationPluginsBootstrapper.java:96) ~[springfox-spring-web-2.9.2.jar:null]
at springfox.documentation.spring.web.plugins.DocumentationPluginsBootstrapper.start(DocumentationPluginsBootstrapper.java:167) ~[springfox-spring-web-2.9.2.jar:null]
at org.springframework.context.support.DefaultLifecycleProcessor.doStart(DefaultLifecycleProcessor.java:178) ~[spring-context-5.3.14.jar:5.3.14]
... 14 common frames omitted
-
报错原因: SpringBoot 与 Swagger2 版本冲突原因。具体的版本冲突范围未测量,我的SpringBoot2.6.2即以上版本都会与Swagger2.9.2及以上版本冲突。
-
解决方案:
-
方案一:将SpringBoot版本降低到2.6以下。我的2.6.2以下就是2.4.5,没报错。
-
方案二:在application.yml文件中添加以下配置
spring:
mvc:
pathmatch:
matching-strategy: ant_path_matcher #解决Spring Boot与Swagger2版本冲突问题