Spring Boot项目集成Knife4j接口文档的实例代码
短信预约 -IT技能 免费直播动态提醒
Knife4j就相当于是swagger的升级版，对于我来说，它比swagger要好用得多
1、在pom.xml引入依赖包
<!-- Swagger配置依赖knife4j -->
<dependency>
<groupId>com.github.xiaoymin</groupId>
<artifactId>knife4j-spring-boot-starter</artifactId>
<version>2.0.9</version>
</dependency>
2、创建Knife4j配置文件
package com.yuyun.config;
import io.swagger.annotations.ApiOperation;
import io.swagger.models.auth.In;
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.ApiKey;
import springfox.documentation.service.Contact;
import springfox.documentation.service.SecurityScheme;
import springfox.documentation.spi.DocumentationType;
import springfox.documentation.spring.web.plugins.Docket;
import springfox.documentation.swagger2.annotations.EnableSwagger2WebMvc;
import java.util.ArrayList;
import java.util.List;
@Configuration
@EnableSwagger2WebMvc
public class Knife4jConfiguration {
@Bean(value = "defaultApi2")
public Docket defaultApi2() {
Docket docket = new Docket(DocumentationType.SWAGGER_2)
// 是否启用Swagger
.enable(true)
//分组名称
.groupName("1.0版本")
// 用来创建该API的基本信息，展示在文档的页面中（自定义展示的信息）
.apiInfo(apiInfo())
// 设置哪些接口暴露给Swagger展示
.select()
// 扫描所有有注解的api，用这种方式更灵活
.apis(RequestHandlerSelectors.withMethodAnnotation(ApiOperation.class))
//指定Controller扫描包路径
// .apis(RequestHandlerSelectors.basePackage("com.yuyun.controller"))
// 扫描所有
// .apis(RequestHandlerSelectors.any())
.build();
return docket;
}
private ApiInfo apiInfo() {
String name = "雨云";
String url = "https://www.xxx.com/";
String email = "1873591403@qq.com";
Contact contact = new Contact(name, url, email);
return new ApiInfoBuilder()
.title("API接口文档")
.description("API接口文档描述")
.termsOfServiceUrl("https://www.xx.com/")
.contact(contact)
.version("1.0.1")
.build();
}
}
注意：如果出现错误Failed to start bean 'documentationPluginsBootstrapper'; nested exception is java.lang.NullPointerException
是因为SpringBoot版本高了，将版本降下去或者在application.yml添加如下内容即可解决该错误
spring:
mvc:
pathmatch:
matching-strategy: ant_path_matcher
项目运行后，访问ip+端口号+/doc.html，比如http://localhost:8110/doc.html。效果如图
3、使用Knife4j注解
（1）在实体类中使用
@ApiModel 放在在响应实体类上，用于描述该类
@ApiModelProperty 描述该响应类的属性
@Data
@ApiModel(value = "企业信息表")
@TableName("company")
public class CompanyDTO implements Serializable {
private static final long serialVersionUID = 1L;
@ApiModelProperty(value = "主键")
private Long id;
@ApiModelProperty(value = "企业名称")
private String companyName;
@ApiModelProperty(value = "简介")
private String description;
}
（2）在Controller层使用
@RestController
@RequestMapping("company")
@Api(tags = "企业信息表")
public class CompanyController {
@Autowired
private CompanyService companyService;
@GetMapping("getList")
@ApiOperation("根据条件获取数据")
@ApiImplicitParams({
@ApiImplicitParam(name = "id", value = "id", paramType = "query", required = true, dataType = "String"),
@ApiImplicitParam(name = "name", value = "名称", paramType = "query", required = true, dataType = "String")
})
public Result<List<CompanyDTO>> getList(@ApiParam(name = "address", value = "地址", required = true) String address) {
List<CompanyDTO> companyList = companyService.list();
return new Result<List<CompanyDTO>>().success(companyList);
}
}
还有其他一些注解，用到再了解
4、全局参数
在实际项目中访问接口都添加了权限，每次访问都要带一个请求头参数token。全局参数就是为了方便传一个固定的参数。当添加全局参数后，所有的接口都会带上该参数。
第一种
在配置文件中加入
private List<SecurityScheme> securitySchemes() {
List<SecurityScheme> apiKeyList = new ArrayList<SecurityScheme>();
apiKeyList.add(new ApiKey("Authorization", "Authorization", In.HEADER.toValue()));
return apiKeyList;
}
在defaultApi2()方法内引用
.securitySchemes(securitySchemes())
最后配置文件中的内容：
@Configuration
@EnableSwagger2WebMvc
public class Knife4jConfiguration {
@Bean(value = "defaultApi2")
public Docket defaultApi2() {
Docket docket = new Docket(DocumentationType.SWAGGER_2)
// 是否启用Swagger
.enable(true)
//分组名称
.groupName("1.0版本")
// 用来创建该API的基本信息，展示在文档的页面中（自定义展示的信息）
.apiInfo(apiInfo())
// 设置哪些接口暴露给Swagger展示
.select()
// 扫描所有有注解的api，用这种方式更灵活
.apis(RequestHandlerSelectors.withMethodAnnotation(ApiOperation.class))
//指定Controller扫描包路径
// .apis(RequestHandlerSelectors.basePackage("com.yuyun.controller"))
// 扫描所有
// .apis(RequestHandlerSelectors.any())
.paths(PathSelectors.any())
.build()
.securitySchemes(securitySchemes())
.securityContexts(securityContexts())
.pathMapping("/");
return docket;
}
private ApiInfo apiInfo() {
String name = "雨云";
String url = "https://www.xxx.com/";
String email = "1873591403@qq.com";
Contact contact = new Contact(name, url, email);
return new ApiInfoBuilder()
.title("API接口文档")
.description("API接口文档描述")
.termsOfServiceUrl("https://www.xx.com/")
.contact(contact)
.version("1.0.1")
.build();
}
private List<SecurityScheme> securitySchemes() {
List<SecurityScheme> apiKeyList = new ArrayList<SecurityScheme>();
apiKeyList.add(new ApiKey("Authorization", "Authorization", "header"));
return apiKeyList;
}
private List<SecurityContext> securityContexts() {
List<SecurityContext> securityContexts = new ArrayList<>();
securityContexts.add(
SecurityContext.builder()
.securityReferences(defaultAuth())
.build());
return securityContexts;
}
private List<SecurityReference> defaultAuth() {
AuthorizationScope authorizationScope = new AuthorizationScope("global", "accessEverything");
AuthorizationScope[] authorizationScopes = new AuthorizationScope[1];
authorizationScopes[0] = authorizationScope;
List<SecurityReference> securityReferences = new ArrayList<>();
securityReferences.add(new SecurityReference("Authorization", authorizationScopes));
return securityReferences;
}
}
效果：菜单上多了一个Authorize，在参数值中添加上信息
刷新一下，再打开接口就会发现多了个请求头部
第二种
直接在菜单文档管理→全局参数设置，然后添加参数：
再打开接口就会发现请求头参数加上了
源码地址：https://gitee.com/hyh17808770899/spring-boot/tree/master/springboot-03
到此这篇关于Spring Boot项目集成Knife4j接口文档的文章就介绍到这了,更多相关Spring Boot集成Knife4j接口文档内容请搜索编程网以前的文章或继续浏览下面的相关文章希望大家以后多多支持编程网！
免责声明：
① 本站未注明“稿件来源”的信息均来自网络整理。其文字、图片和音视频稿件的所属权归原作者所有。本站收集整理出于非商业性的教育和科研之目的，并不意味着本站赞同其观点或证实其内容的真实性。仅作为临时的测试数据，供内部测试之用。本站并未授权任何人以任何方式主动获取本站任何信息。
② 本站未注明“稿件来源”的临时测试数据将在测试完成后最终做删除处理。有问题或投稿请发送至: 邮箱/279061341@qq.com QQ/279061341
