spring boot 集成 knife4j

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")@ResponseBodypublic 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);}}