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")
    @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、展示结果

相关推荐
李少兄30 分钟前
Unirest:优雅的Java HTTP客户端库
java·开发语言·http
此木|西贝36 分钟前
【设计模式】原型模式
java·设计模式·原型模式
可乐加.糖1 小时前
一篇关于Netty相关的梳理总结
java·后端·网络协议·netty·信息与通信
s9123601011 小时前
rust 同时处理多个异步任务
java·数据库·rust
9号达人1 小时前
java9新特性详解与实践
java·后端·面试
cg50171 小时前
Spring Boot 的配置文件
java·linux·spring boot
啊喜拔牙1 小时前
1. hadoop 集群的常用命令
java·大数据·开发语言·python·scala
anlogic2 小时前
Java基础 4.3
java·开发语言
非ban必选2 小时前
spring-ai-alibaba第七章阿里dashscope集成RedisChatMemory实现对话记忆
java·后端·spring
A旧城以西2 小时前
数据结构(JAVA)单向,双向链表
java·开发语言·数据结构·学习·链表·intellij-idea·idea