knife4j swagger 使用笔记

访问Knife4j的文档地址：http://ip:port/doc.html

1.接口访问的端口跟后台设置的不一致，接口请求无反应 处理办法

2.响应参数不显示问题

（1）返回的参数里面一定要有响应的参数对象，如下：

（2）TableDataInfo 定义成泛型类 TableDataInfo

package com.dcqq.common.core.page;

import java.io.Serializable;
import java.util.List;

/**
 * 表格分页数据对象
 *
 * @author ruoyi
 */
public class TableDataInfo<T> implements Serializable {
    private static final long serialVersionUID = 1L;

    /**
     * 总记录数
     */
    private long total;

    /**
     * 列表数据
     */
    private T rows;

    /**
     * 消息状态码
     */
    private int code;

    /**
     * 消息内容
     */
    private String msg;

    /**
     * 表格数据对象
     */
    public TableDataInfo() {
    }

    /**
     * 分页
     *
     * @param list  列表数据
     * @param total 总记录数
     */
    public TableDataInfo(T list, int total) {
        this.rows = list;
        this.total = total;
    }

    public long getTotal() {
        return total;
    }

    public void setTotal(long total) {
        this.total = total;
    }

    public T getRows() {
        return rows;
    }

    public void setRows(T rows) {
        this.rows = rows;
    }

    public int getCode() {
        return code;
    }

    public void setCode(int code) {
        this.code = code;
    }

    public String getMsg() {
        return msg;
    }

    public void setMsg(String msg) {
        this.msg = msg;
    }
}

3.枚举类文档展示自动转换

效果：

注意：目前只实现了post请求，其他未能实现

（1）自定义：SwaggerDisplayEnum

package com.dcqq.common.annotation;

import java.lang.annotation.ElementType;
import java.lang.annotation.Retention;
import java.lang.annotation.RetentionPolicy;
import java.lang.annotation.Target;

@Target({ ElementType.TYPE })
@Retention(RetentionPolicy.RUNTIME)
public @interface SwaggerDisplayEnum {
    String value() default "value";
    String desc() default "desc";
}

（2）自定义拓展处理器 SwaggerEnumBuilderPlugin

package com.dcqq.common.config;

import cn.hutool.core.util.ReflectUtil;
import com.dcqq.common.annotation.SwaggerDisplayEnum;
import com.dcqq.common.utils.StringUtils;
import io.swagger.annotations.ApiModelProperty;
import org.springframework.context.annotation.Primary;
import org.springframework.core.annotation.AnnotationUtils;
import org.springframework.stereotype.Component;
import springfox.documentation.schema.Annotations;
import springfox.documentation.spi.DocumentationType;
import springfox.documentation.spi.schema.ModelPropertyBuilderPlugin;
import springfox.documentation.spi.schema.contexts.ModelPropertyContext;

import java.util.Arrays;
import java.util.Objects;
import java.util.Optional;
import java.util.stream.Collectors;

@Component
@Primary
public class SwaggerEnumBuilderPlugin implements ModelPropertyBuilderPlugin {
    @Override
    public void apply(ModelPropertyContext context) {
        Optional<ApiModelProperty> reference = Optional.empty();

        // 找到 @ApiModelProperty 注解修饰的枚举类
        if (context.getBeanPropertyDefinition().isPresent()) {
            reference = Annotations.findPropertyAnnotation(context.getBeanPropertyDefinition().get(), ApiModelProperty.class);
        }

        //没有@ApiModelProperty 或 reference 为空 直接返回
        if (!reference.isPresent() || StringUtils.isEmpty(reference.get().reference())) {
            return;
        }

        // 生成需要拼接的取值含义描述内容
        String valueDesc = generateValueDesc(reference.get());
        context.getSpecificationBuilder().description(valueDesc);
    }

    private String generateValueDesc(ApiModelProperty property) {
        String enumFullDesc = null;
        try {
            Class<? extends Enum> rawPrimaryType = (Class<? extends Enum>) Class.forName(property.reference());
            SwaggerDisplayEnum swaggerDisplayEnum = AnnotationUtils.findAnnotation(rawPrimaryType,
                    SwaggerDisplayEnum.class);
            enumFullDesc = Arrays.stream(rawPrimaryType.getEnumConstants())
                    .filter(Objects::nonNull)
                    .map(enumConsts -> {
                        Object fieldValue = ReflectUtil.getFieldValue(enumConsts, swaggerDisplayEnum.value());
                        Object fieldDesc = ReflectUtil.getFieldValue(enumConsts, swaggerDisplayEnum.desc());
                        return fieldValue + "-" + fieldDesc;
                    }).collect(Collectors.joining(";"));
        } catch (ClassNotFoundException e) {
            throw new RuntimeException(e);
        }
        return property.value()+"(" + enumFullDesc + ")";
    }

    @Override
    public boolean supports(DocumentationType delimiter) {
        return true;
    }
}

（3）示例枚举

package com.dcqq.common.enums;

import com.dcqq.common.annotation.SwaggerDisplayEnum;
import lombok.Getter;

/**
 * 订单消息
 */
@Getter
@SwaggerDisplayEnum(value = "value",desc = "desc")//注意：“value”和“desc”必须和定义的属性保存一致
public enum MsgTypeEnum {
    XD_CG("下单成功通知","1"),
    YFH("已发货通知","2"),
    QS_TX("已签收提醒","3"),
    QX("取消通知","9");

    private String desc; //描述
    private String value; //值

    MsgTypeEnum(String desc, String value) {
        this.desc = desc;
        this.value = value;
    }
}

（4）示例MsgController

package com.dcqq.app;

import com.dcqq.common.core.controller.BaseController;
import com.dcqq.common.core.page.TableDataInfo;
import com.dcqq.common.utils.SecurityUtils;
import com.dcqq.system.domain.TShopOrderMsg;
import com.dcqq.system.service.ITShopOrderMsgService;
import io.swagger.annotations.Api;
import io.swagger.annotations.ApiOperation;
import org.springframework.beans.factory.annotation.Autowired;
import org.springframework.web.bind.annotation.*;

import java.util.List;

/**
 * 消息管理Controller
 *
 * @author zd
 * @date 2024-01-10
 */
@RestController
@Api(tags = "消息管理")
@RequestMapping("/test/msg")
public class MsgController extends BaseController {

    @Autowired
    private ITMsgService msgService;

    @PostMapping("/list")
    @ApiOperation("查询消息管理列表")
    public TableDataInfo<List<Msg>> list(@RequestBody Msg msg) {
        startPage();
        List<Msg> list = msgService.selectMsgList(msg);
        return getDataTable(list);
    }
}

（5）实体类

关键代码：reference = “com.common.enums.MsgTypeEnum”

package com.system.domain;

import com.baomidou.mybatisplus.annotation.IdType;
import com.baomidou.mybatisplus.annotation.TableField;
import com.baomidou.mybatisplus.annotation.TableId;
import com.dcqq.common.annotation.ApiPropertyReference;
import com.dcqq.common.annotation.Excel;
import com.dcqq.common.core.domain.BaseEntity;
import com.dcqq.common.enums.MsgTypeEnum;
import io.swagger.annotations.ApiModelProperty;
import lombok.Data;

import java.math.BigDecimal;

/**
 * 消息对象 
 * 
 * @author 
 * @date 2024-04-25
 */
@Data
public class TShopOrderMsg{
    private static final long serialVersionUID = 1L;

    @TableId(type = IdType.AUTO)
    /** 主键 */
    @ApiModelProperty("主键")
    private Long id;

    /** 删除标志（0代表存在 2代表删除） */
    @ApiModelProperty("删除标志（0代表存在 2代表删除）")
    private String delFlag;

    /** 消息类型（{@link com.common.enums.MsgTypeEnum}） */
    @Excel(name = "消息类型")
    @ApiModelProperty(value = "消息类型",reference = "com.common.enums.MsgTypeEnum")
    private String msgType;
}

（6）maven相关

<dependency>
    <groupId>io.springfox</groupId>
    <artifactId>springfox-boot-starter</artifactId>
    <version>3.0.0</version>
    <exclusions>
        <exclusion>
            <groupId>io.swagger</groupId>
            <artifactId>swagger-models</artifactId>
        </exclusion>
    </exclusions>
</dependency>
<dependency>
    <groupId>com.github.xiaoymin</groupId>
    <artifactId>knife4j-spring-boot-starter</artifactId>
    <version>3.0.3</version>
</dependency>
<dependency>
    <groupId>io.swagger</groupId>
    <artifactId>swagger-models</artifactId>
    <version>1.6.14</version>
</dependency>
<dependency>
   <groupId>cn.hutool</groupId>
   <artifactId>hutool-all</artifactId>
   <version>5.8.27</version>
</dependency>

参考：
https://blog.csdn.net/l121lpanxun/article/details/125297645
https://blog.gelu.me/2021/Knife4j-Swagger%E8%87%AA%E5%AE%9A%E4%B9%89%E6%9E%9A%E4%B8%BE%E7%B1%BB%E5%9E%8B/
https://cloud.tencent.com/developer/article/2105433

4.token设置