1、knife4j介绍以及环境介绍
knife4j是为Java MVC框架集成Swagger生成Api文档的增强解决方案,前身是swagger-bootstrap-ui,取名knife4j是希望它能像一把匕首一样小巧,轻量,并且功能强悍!其底层是对Springfox的封装，使用方式也和Springfox一致，只是对接口文档UI进行了优化。
jdk为1.8 ，springboot 2.7.3、knife4j的版本3.0.3。
2、pom依赖
<dependency>
<groupId>com.github.xiaoymin</groupId>
<artifactId>knife4j-spring-boot-starter</artifactId>
<version>3.0.3</version>
</dependency>
3、代码样例
1、开启swagger以及knife4j配置代码
package com.example.demo.config;
import com.github.xiaoymin.knife4j.spring.annotations.EnableKnife4j;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import org.springframework.context.annotation.Import;
import springfox.bean.validators.configuration.BeanValidatorPluginsConfiguration;
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.EnableSwagger2;
@Configuration
@EnableSwagger2//该注解是Springfox-swagger框架提供的使用Swagger注解，该注解必须加
@EnableKnife4j//该注解是knife4j提供的增强注解,Ui提供了例如动态参数、参数过滤、接口排序等增强功能,
//如果你想使用这些增强功能就必须加该注解，否则可以不用加
@Import(BeanValidatorPluginsConfiguration.class)
public class SwaggerConfiguration {
@Bean(value = "defaultApi2")
public Docket defaultApi2() {
Docket docket = new Docket(DocumentationType.SWAGGER_2)
.apiInfo(apiInfo())
//分组名称
.groupName("1.X版本")
.select()
//这里指定Controller扫描包路径
.apis(RequestHandlerSelectors.basePackage("com.example.demo.controller"))
.paths(PathSelectors.any())
.build();
return docket;
}
private ApiInfo apiInfo() {
return new ApiInfoBuilder()
.title("项目标题")
.description("描述")
.termsOfServiceUrl("服务Url")
.contact(new Contact("DAIHAO", "", ""))
.version("1.0")
.build();
}
}
2、请求参数代码，需要使用ApiModel和ApiModelProperty 注解
package com.example.demo.model;
import io.swagger.annotations.ApiModel;
import io.swagger.annotations.ApiModelProperty;
import lombok.Data;
import javax.validation.constraints.NotNull;
@Data
@ApiModel(value = "订单分页查询对象")
public class OrderQuery {
@ApiModelProperty(value = "订单查询开始时间")
private String startTime;
@ApiModelProperty(value = "订单查询结束时间")
private String endTime;
@NotNull(message = "分页不能为空")
@ApiModelProperty(value = "每页显示的数量", required = true, example = "15")
private Integer pageSize;
@NotNull(message = "当前页不能为空")
@ApiModelProperty(value = "当前页", required = true, example = "1")
private Integer pageNo;
@ApiModelProperty(value = "订单编号")
private String id;
@ApiModelProperty(value = "订单原始编号")
private Long oid;
}
返回参数代码，也是要ApiModel和ApiModelProperty 注解
全局返回实体
package com.example.demo.po;
import io.swagger.annotations.ApiModel;
import io.swagger.annotations.ApiModelProperty;
import lombok.Data;
import java.io.Serializable;
package com.example.demo.po;
import io.swagger.annotations.ApiModel;
import io.swagger.annotations.ApiModelProperty;
import lombok.Data;
import java.io.Serializable;
/**
* @date 2023年03月27日 14:02
*/
@Data
@ApiModel("返回体")
public class ResultVO<T> implements Serializable {
@ApiModelProperty(value = "返回状态码，0：表示成功，1表示失败")
private String code ;
@ApiModelProperty(value = "返回描述")
private String message ;
@ApiModelProperty(value = "数据体")
private T data ;
public ResultVO(String code, String message, T data) {
this.code = code;
this.message = message;
this.data = data;
}
public static ResultVO success(Object data){
return new ResultVO("0","成功",data);
}
public ResultVO fail( ){
return new ResultVO("1","失败",null);
}
}
@Data
@ApiModel("返回体")
public class ResultVO<T> implements Serializable {
@ApiModelProperty(value = "返回状态码，0：表示成功，1表示失败")
private String code ;
@ApiModelProperty(value = "返回描述")
private String message ;
@ApiModelProperty(value = "数据体")
private T data ;
public ResultVO(String code, String message, T data) {
this.code = code;
this.message = message;
this.data = data;
}
public static ResultVO success(Object data){
return new ResultVO("0","成功",data);
}
public ResultVO fail( ){
return new ResultVO("1","失败",null);
}
}
泛型体返回举例
package com.example.demo.model;
import com.fasterxml.jackson.annotation.JsonFormat;
import io.swagger.annotations.ApiModel;
import io.swagger.annotations.ApiModelProperty;
import lombok.Data;
import javax.validation.Valid;
import java.util.Date;
import java.util.List;
/**
* @date 2023年05月05日 13:31
*/
@Data
@ApiModel("订单实体")
public class Order {
@Valid
@ApiModelProperty(value = "订单编号")
private String id;
@ApiModelProperty(value = "订单原始编号")
private Long oid ;
@ApiModelProperty("订单名称")
private String name1 ;
@JsonFormat(pattern="yyyy-MM-dd HH:mm:ss",timezone = "GMT+8")
private Date date1 ;
@ApiModelProperty(value = "子订单列表")
private List<OrderItem> orderItemList;
}
控制器代码示例，需要使用Api、ApiOperation注解
package com.example.demo.controller;
import com.example.demo.model.Order;
import com.example.demo.model.OrderItem;
import com.example.demo.model.OrderQuery;
import com.example.demo.po.ResultVO;
import io.swagger.annotations.Api;
import io.swagger.annotations.ApiOperation;
import org.springframework.web.bind.annotation.*;
import java.util.ArrayList;
import java.util.List;
@RestController
@RequestMapping("/order")
@Api(tags = "订单管理")
public class OrderContronller {
@ApiOperation("订单列表接口")
@PostMapping("getOrderList")
@ResponseBody
public ResultVO<Order> getOrderList(@RequestBody OrderQuery orderQuery){
Order order = new Order();
order.setId("123423");
order.setOid(123444L);
OrderItem orderItem = new OrderItem();
orderItem.setOrderItemId("133");
orderItem.setPrice(1000l);
orderItem.setName("手机");
List<OrderItem> orderItemList = new ArrayList<>();
orderItemList.add(orderItem);
order.setOrderItemList(orderItemList);
return ResultVO.success(order);
}
}
4、展示结果
