关于knife4j
Knife4j是一个基于Swagger的Java接口文档生成工具,它提供了一套可视化的界面来展示和测试API接口。Knife4j通过解析接口代码中的Swagger注解,自动生成接口文档,并提供了交互式的API文档界面,方便开发者查看和测试接口。引用官方的一句描述Knife4j是一个集Swagger2 和 OpenAPI3 为一体的增强解决方案
安装配置
1、依赖引入
<dependency>
<groupId>com.github.xiaoymin</groupId>
<artifactId>knife4j-spring-boot-starter</artifactId>
<version>2.0.9</version>
</dependency>
// 如果已经配置了swagger需要将swagger相关的依赖删除
2、配置knife4j
package com.example.common.conf;
import io.swagger.annotations.ApiOperation;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import springfox.documentation.builders.ApiInfoBuilder;
import springfox.documentation.builders.RequestHandlerSelectors;
import springfox.documentation.service.*;
import springfox.documentation.spi.DocumentationType;
import springfox.documentation.spring.web.plugins.Docket;
import springfox.documentation.swagger2.annotations.EnableSwagger2WebMvc;
/**
* @ClassName: SwaggerConfig
* @Description: swagger配置文件
* @Author: WangBin
* @Date: 2023/5/18 23:35
* 访问地址:http://localhost:8080/demo/swagger-ui.html#
*/
@Configuration
@EnableSwagger2WebMvc
public class SwaggerConfig {
@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.cnblogs.com/tanxj/";
String email = "[email protected]";
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();
}
}
这样就配置完成了,启动您的Spring Boot应用程序,并访问Knife4j的API文档界面。默认情况下,文档界面的URL为
http://localhost:端口号/doc.html
。
3、问题处理
启动失败
启动出现这个问题:Failed to start bean 'documentationPluginsBootstrapper'; nested exception is java.lang.NullPointerException
解决办法:在
application.yml
添加以下配置
spring:
mvc:
pathmatch:
matching-strategy: ant_path_matcher
页面访问被拦截
这个一般是配置了拦截器或者SpringSecurity之类的东西把它拦截的,我这个项目中是因为我配置的拦截器拦截了,只要在过滤器中放过对应的资源就好,具体代码可以参考我另一篇博客:传送门
4、接口上使用示例
@RestController
@RequestMapping("/user")
@Api(description = "用户管理")
public class UserController {
@Autowired
private UserService userService;
/**
* 系统登录
* @param userAccount 账号
* @param userPassword 密码
* @return
*/
@RequestMapping(value = "/login", method = RequestMethod.GET)
@ApiOperation(value = "登录", notes = "用户登录接口")
public ResultBean login(@RequestParam("userAccount") String userAccount, @RequestParam("userPassword") String userPassword) {
log.info("系统登录,账号:{},密码:{}", userAccount, userPassword);
return userService.login(userAccount, userPassword);
}
..........................