当前位置：首页 > article >正文

spring boot 集成 knife4j

article 2025/1/13 8:13:40

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);
    }

}