四、Java中SpringBoot组件集成接入【Knife4j接口文档（swagger增强）】
- 1.Knife4j介绍
- 2.maven依赖
- 3.配置类
- 4.常用注解使用
- 1.实体类及属性（@ApiModel和@ApiModelProperty）
- 2.控制类及方法（@Api、@ApiOperation、@ApiImplicitParam、 @ApiResponses）
- 3.@ApiOperationSupport注解未生效的解决方法
- 5.效果展示
- 6.参考文章
1.Knife4j介绍
Knife4j是一款基于Swagger的开源API文档管理工具，具有易用性和丰富的功能。它可以方便地生成和展示RESTful API接口文档，并提供了强大的交互式界面。
Knife4j具有以下主要特点：
- 集成Swagger：Knife4j是在Swagger UI基础上进行扩展和优化的，能够完美兼容Swagger的注解和配置，生成符合OpenAPI规范的API文档。
- 强大的交互式界面：Knife4j的界面友好、美观，提供了接口测试、调试和在线调用等功能，使得开发者可以更方便地与API进行交互。
- 自动生成接口文档：通过Knife4j的各种注解，开发人员可以方便地在代码中定义接口信息和参数说明，然后Knife4j会根据这些注解自动生成API文档，减少了手动维护文档的工作量。
- 接口权限管理：Knife4j支持对API接口进行权限管理，可以通过配置权限策略，限制只有授权用户才能够访问和调用指定的接口。
- 支持自定义扩展：Knife4j支持自定义主题样式、接口分类、接口分组等功能，可以根据实际需求进行个性化定制。
总的来说，Knife4j简化了API文档的编写和管理工作，提供了交互性强、易于使用的界面，方便开发团队进行接口开发和测试工作。它是一款非常实用的API文档管理工具。
参考：Knife4j官方文档
2.maven依赖
<!--knife4j依赖库-->
<dependency>
<groupId>com.github.xiaoymin</groupId>
<artifactId>knife4j-spring-boot-starter</artifactId>
<version>3.0.3</version>
</dependency>
3.配置类
import com.github.xiaoymin.knife4j.spring.annotations.EnableKnife4j;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import org.springframework.core.env.Environment;
import org.springframework.core.env.Profiles;
import springfox.documentation.builders.ApiInfoBuilder;
import springfox.documentation.builders.PathSelectors;
import springfox.documentation.builders.RequestHandlerSelectors;
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
@EnableKnife4j
public class Knife4jConfig {
@Bean
public Docket createRestApi(Environment environment) {
//设置显示的swagger环境信息,判断是否处在自己设定的环境当中,为了安全生产环境不开放Swagger
Profiles profiles = Profiles.of("dev", "test");
boolean flag = environment.acceptsProfiles(profiles);
//创建一个Docket的对象，相当于是swagger的一个实例
return new Docket(DocumentationType.SWAGGER_2)
.useDefaultResponseMessages(false)
.groupName("1.x版本")
.apiInfo(new ApiInfoBuilder()
.description("API调试文档")//描述
.contact(new Contact("funfan", "http://ip地址:10517/doc.html", "1424393744@qq.com"))//作者信息
.version("v1.0")//版本
.title("服务API文档")//标题
.termsOfServiceUrl("")//服务Url
.build())
// .enable(flag)//只有当springboot配置文件为dev或test环境时，才开启swaggerAPI文档功能
.select() // 这里指定Controller扫描包路径:设置要扫描的接口类，一般是Controller类
.apis(RequestHandlerSelectors.basePackage("com.funfan.autoCodeDemo.manage.controller")) //这里采用包扫描的方式来确定要显示的接口
// .apis(RequestHandlerSelectors.withMethodAnnotation(ApiOperation.class)) //这里采用包含注解的方式来确定要显示的接口
.paths(PathSelectors.any())// 配置过滤哪些，设置对应的路径才获取
.build();
}
}
4.常用注解使用
1.实体类及属性（@ApiModel和@ApiModelProperty）
@ApiModel：用于响应类上，表示一个返回响应数据的信息
@ApiModelProperty：用在属性上，描述响应类的属性
@ApiModel(value = "RestResponse<T>", description = "响应通用参数包装")
@Data
public class RestResponse<T> {
@ApiModelProperty("响应错误编码,1为正常")
private int code;
@ApiModelProperty("响应错误信息")
private String msg;
@ApiModelProperty("响应内容")
private T result;
......(略)
}
2.控制类及方法（@Api、@ApiOperation、@ApiImplicitParam、 @ApiResponses）
- @Api：用在请求的类上，说明该类的作用
- @ApiOperation：用在请求的方法上，说明方法的作用
- @ApiImplicitParam：用在 @ApiImplicitParams 注解中，指定一个请求参数的配置信息
name：参数名
value：参数的汉字说明、解释
required：参数是否必须传
paramType：参数放在哪个地方
· header --> 请求参数的获取：@RequestHeader
· query --> 请求参数的获取：@RequestParam
· path（用于restful接口）–> 请求参数的获取：@PathVariable
· body（不常用）
· form（不常用）
dataType：参数类型，默认String，其它值dataType=“Integer”
defaultValue：参数的默认值 - @ApiResponse：用在@ApiResponses中，一般用于表达一个错误的响应信息
code：数字，例如400
message：信息，例如"请求参数没填好"
response：抛出异常的类 - @ApiOperationSupport：用于配置和定制API接口的展示信息。
author：指定API接口作者的名称。 oAuthUrls：指定需要进行OAuth授权的URL路径集合。
visibility：指定API接口的可见性，默认为 PUBLIC。
responseHeaders：指定API接口的响应头信息。
deprecated：指定API接口是否已被废弃，默认为 false。
hidden：指定API接口是否隐藏，默认为false。
tags：指定API接口所属的标签。
@Api(tags = "首页模块")
@RestController
public class IndexController {
@ApiOperation(value = "向客人问好",notes = "向客人问好")
@ApiImplicitParams({
@ApiImplicitParam(name="userName", value="名字", required=true, paramType="form"),
@ApiImplicitParam(name="password",value="密码",required=true,paramType="form"),
})
@ApiResponses({
@ApiResponse(code=400,message="请求参数没填好"),
@ApiResponse(code=404,message="请求路径没有或页面跳转路径不对")
})
@ApiOperationSupport(order = 1,author = "1424393744@qq.com", ignoreParameters = {"userId"})
@ResponseBody
@RequestMapping(value = "/sayHi.do", method = {RequestMethod.POST})
public RestResponse<String> sayHi(@RequestBody @Validated User user){
return RestResponse.success("Hi:"+user);
}
}
3.@ApiOperationSupport注解未生效的解决方法
在application.yaml配置文件中启用knife4j增强
knife4j:
# 开启增强配置
enable: true
# 开启生产环境屏蔽 production: true时就访问不了swagger了
production: false
5.效果展示
开启服务，根据自身服务号访问：【ip:端口号/doc.html】
我的服务端口号10517，就访问http://127.0.0.1:10517/doc.html
6.参考文章
Java 后端整合 Swagger + Knife4j 接口文档
swagger2 注解说明
SpringBoot常用注解
