目录
介绍
Knife4j是为Java MVC框架集成Swagger生成在线Api文档的增强解决方案,其前身是swagger-bootstrap-ui,此框架还有调试功能,可以向服务器端发送请求,并获取响应结果。简单的说就是帮我们自动生成了文档注解,而且可以直接在图形化界面中向服务器发起请求,便于调试。
使用步骤
1.在maven中添加依赖
<dependency>
<groupId>com.github.xiaoymin</groupId>
<artifactId>knife4j-spring-boot-starter</artifactId>
<version>2.0.9</version>
</dependency>
2.添加其配置类,可以放在项目其他框架的配置类包中
import com.github.xiaoymin.knife4j.spring.extension.OpenApiExtensionResolver;
import lombok.extern.slf4j.Slf4j;
import org.springframework.beans.factory.annotation.Autowired;
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.Contact;
import springfox.documentation.spi.DocumentationType;
import springfox.documentation.spring.web.plugins.Docket;
import springfox.documentation.swagger2.annotations.EnableSwagger2WebMvc;
/**
* Knife4j配置类
*
* @author lee
* @version 0.0.1
*/
@Slf4j
@Configuration
@EnableSwagger2WebMvc
public class Knife4jConfiguration {
/**
* 【重要】指定Controller包路径
*/
private String basePackage = "com.lee.test.product.controller";
/**
* 分组名称
*/
private String groupName = "product";
/**
* 主机名
*/
private String host = "http://lee.com";
/**
* 标题
*/
private String title = "演示在线API文档--商品管理";
/**
* 简介
*/
private String description = "演示在线API文档--商品管理";
/**
* 服务条款URL
*/
private String termsOfServiceUrl = "http://www.apache.org/licenses/LICENSE-2.0";
/**
* 联系人
*/
private String contactName = "lee-coding";
/**
* 联系网址
*/
private String contactUrl = "lee-coding.blog.csdn.net";
/**
* 联系邮箱
*/
private String contactEmail = "lee@xx.mail";
/**
* 版本号
*/
private String version = "1.0.0";
@Autowired
private OpenApiExtensionResolver openApiExtensionResolver;
public Knife4jConfiguration() {
log.debug("加载配置类:Knife4jConfiguration");
}
@Bean
public Docket docket() {
String groupName = "1.0.0";
Docket docket = new Docket(DocumentationType.SWAGGER_2)
.host(host)
.apiInfo(apiInfo())
.groupName(groupName)
.select()
.apis(RequestHandlerSelectors.basePackage(basePackage))
.paths(PathSelectors.any())
.build()
.extensions(openApiExtensionResolver.buildExtensions(groupName));
return docket;
}
private ApiInfo apiInfo() {
return new ApiInfoBuilder()
.title(title)
.description(description)
.termsOfServiceUrl(termsOfServiceUrl)
.contact(new Contact(contactName, contactUrl, contactEmail))
.version(version)
.build();
}
}
以上内容可以选择复制粘贴。
3.application.properties中添加配置
#..
knife4j.enable=true
注意:
当前项目的Spring Boot版本是2.5.9,必须是2.6以下的版本(2.6不可用)如果要使用更高版本的Spring Boot,必须使用更高版本的Knife4j
在配置类中的basePackage
必须是控制器类所在的包
完成后,启动项目,通过 /doc.html
即可访问在线API文档。界面效果:
这时我们看到的就是knife4j提供给我们的界面,左边这一列会列出所有的controller,以及里面的所有处理请求的方法,现在我们加入一个ProductController 控制器类:
@Slf4j
@RestController
@RequestMapping("/products")
public class ProductController {
public ProductController(){
log.debug("创建商品控制器");
}
@RequestMapping("/add-new")
public String addNew(){
return "添加成功";
}
}
然后再次运行启动类,刷新页面看到如下效果
我们可以看到在接口统计信息中已经多出了7个接口相关信息,并在左侧图中多出了我们所创建的ProductController。虽然我们只有一个处理请求的方法,但由于我们没有定义具体的请求方式,所以框架帮我们列出了所有的请求方式。因为是添加产品业务,所以我们改为Post请求,另外框架还为我们提供了很丰富的注解,例如:@Api,可以在控制器类上面添加并设置tags属性 @ApiOperation,可以在控制器类中处理请求的对应方法上面添加,并配置value属性,代码如下:
这时我们再看前端展示页面:
类名和方法名都改为了中文,而且请求方式也发生了改变。我们点击处理添加请求的方法:
可以看到里面有详细的请求参数,相应类型等等,由于我们的方法中未定义任何参数和业务逻辑,所以显示为空,现在我们为addNew这个方法传入一个ProductAddNewDTO数据传输对象,并在这个类中定义几个变量。如下代码:
@Slf4j
@Api(tags = "商品管理模块")
@RestController
@RequestMapping("/products")
public class ProductController {
public ProductController(){
log.debug("创建商品控制器");
}
@ApiOperation(value = "添加产品")
@PostMapping("/add-new")
public String addNew(ProductAddNewDTO productAddNewDTO){
return "添加成功";
}
}
@Data
@Accessors(chain = true)
public class ProductAddNewDTO {
private String name;
private String description;
private Integer id;
}
添加成功后,我们再去前端页面就会看到参数列表 ,以及对应的信息和属性:
点击调试,还可以直接向服务器发送请求,获取响应信息:
以上就是简单的使用介绍。当然其中还有很多实用的注解,以及功能特效。这里就不一一赘述,大家感兴趣可以自己研究一下