Springboot 2.7 集成 Swagger 增强版接口框架 Knife4j 4.3 + springdoc OpenApi 3.0_百度小程序

您的位置：上海毫米网络优化公司 > 小程序 > 百度小程序 >

文章目录

1 摘要
2 核心 Maven 依赖
3 核心代码

3.1 application 配置
3.2 openApi 配置类
3.3 POJO 类使用示例

3.3.1 实体类
3.3.2 请求参数
3.3.3 公共返回参数(包含泛型)
3.4 Controller 控制层示例
4 升级注意事项(踩坑指南)

4.1 Swagger 2 注解替换
4.2 公共返回参数不能使用 `@Schema` 注解，否则就会只生成一个 `Swagger Model`
4.3 Get 请求参数前需要添加 `@ParamterObject` 注解
5 使用效果

5.1 导出到 Postman 等测试工具的接口数据地址
5.2 Knife4j 导出接口文档
5.3 Knife4j UI 界面
5.4 Swagger UI 界面
6 推荐参考资料

7 Github 源码

1 摘要

Swagger 作为一款服务端接口文档自动生成框架，早已深入人心，并且在市场上得到了广泛的应用。然而，Swagger 3.0 也就是 OpenApi 3.0 规范发布之后便停止了更新维护，出道就是巅峰。Knife4j 作为 Swagger 的增强版，是对 Swagger UI 做了优化，同时还有很多增强的功能。伴随着 Swagger 3.0 的停止更新，如今 Knife4j 从4.0开始已经逐渐使用 Springdoc 作为 swagger 的替代。Springdoc 针对 OpenApi 3.0 的适配做了较大的调整，其中注解与 Swagger 2 的基本不通用。作为新项目而言，使用社区维护活跃的开源框架显得非常重要。本文将介绍基于 Springboot 2.7 集成 Swagger 的增强框架 Knife4j 4.3 + Springdoc OpenApi 3.0 。

Knife4j 官方文档: https://doc.xiaominfo.com/docs/quick-start

Springdoc 官方文档: https://springdoc.org

2 核心 Maven 依赖

demo-knife4j-openapi3/pom.xml

        
        
            com.github.xiaoymin
            knife4j-openapi3-spring-boot-starter
            ${knife4j-openapi3-spring.version}

版本信息

4.3.0

注意事项:

本示例中使用的是 Springboot 2.7 版本，如果是 sprigboot 3.0 + 版本，则对应的 maven 依赖为:


    com.github.xiaoymin
    knife4j-openapi3-jakarta-spring-boot-starter
    4.3.0

3 核心代码

3.1 application 配置

demo-knife4j-openapi3/src/main/resources/application.yml

springdoc 相关配置:

# spring-doc 接口文档
springdoc:
  api-docs:
    enabled: true # 是否启用接口文档
knife4j:
  enable: true # 是否启用 knife4j 增强,如果只是使用 knife4j 的 UI,则可以关闭

3.2 openApi 配置类

demo-knife4j-openapi3/src/main/java/com/ljq/demo/springboot/knife4j/common/config/OpenApiConfig.java

package com.ljq.demo.springboot.knife4j.common.config;
import io.swagger.v3.oas.models.ExternalDocumentation;
import io.swagger.v3.oas.models.OpenAPI;
import io.swagger.v3.oas.models.info.Contact;
import io.swagger.v3.oas.models.info.Info;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
/**
 * @Description: openapi 界面配置
 * @Author: junqiang.lu
 * @Date: 2023/8/15
 */
@Configuration
public class OpenApiConfig {
    @Bean
    public OpenAPI springShopOpenAPI() {
        return new OpenAPI()
                // 接口文档标题
                .info(new Info().title("Knife4j OpenApi 3")
                        // 接口文档描述
                        .description("Knife4j OpenApi 3 example application")
                        // 接口文档版本
                        .version("v1.0")
                        // 开发者联系方式
                        .contact(new Contact().name("Flying9001").url("https://github.com/Flying9001")))
                .externalDocs(new ExternalDocumentation()
                        // 额外补充说明
                        .description("Github example code")
                        // 额外补充链接
                        .url("https://github.com/Flying9001/springBootDemo/demo-knife4j-openapi3"));
    }
    
}

3.3 POJO 类使用示例

3.3.1 实体类

demo-knife4j-openapi3/src/main/java/com/ljq/demo/springboot/knife4j/model/entity/UserPushTypeEntity.java

package com.ljq.demo.springboot.knife4j.model.entity;
import com.baomidou.mybatisplus.annotation.TableName;
import com.ljq.demo.springboot.knife4j.model.BaseEntity;
import io.swagger.v3.oas.annotations.media.Schema;
import lombok.Data;
import lombok.ToString;
/**
 * 用户消息推送方式实体类
 *
 * @author junqiang.lu
 * @date 2023-08-15 14:26:38
 */
@Data
@ToString(callSuper = true)
@Schema(description = "用户消息推送方式")
@TableName(value = "user_push_type")
public class UserPushTypeEntity extends BaseEntity {
	private static final long serialVersionUID = 1L;
	@Schema(description = "用户id")
	private Long userId;
	@Schema(description = "推送方式,1-短信;2-邮件;3-app;4-wechat")
	private Integer pushType;
	@Schema(description = "通知推送接收地址")
	private String receiveAddress;
	@Schema(description = "是否启用,0-未启用,1-启用")
	private Integer enable;
}

原来 Swagger 2 的 @Apimodel 以及 @ApiModelPropertity 注解全部使用 @Schema 注解代替

3.3.2 请求参数

demo-knife4j-openapi3/src/main/java/com/ljq/demo/springboot/knife4j/model/param/userpushtype/UserPushTypeSaveParam.java

package com.ljq.demo.springboot.knife4j.model.param.userpushtype;
import io.swagger.v3.oas.annotations.media.Schema;
import lombok.Data;
import javax.validation.constraints.NotBlank;
import javax.validation.constraints.NotNull;
import java.io.Serializable;
/**
 * 用户消息推送方式参数接收类
 *
 * @author junqiang.lu
 * @date 2023-08-14 17:17:19
 */
@Data
@Schema(description = "用户消息推送方式保存(单条)")
public class UserPushTypeSaveParam implements Serializable {
    private static final long serialVersionUID = 1L;
    @NotNull(message = "用户id 不能为空")
    @Schema(description = "用户id", requiredMode = Schema.RequiredMode.REQUIRED)
    private Long userId;
    @NotNull(message = "推送方式不能为空")
    @Schema(description = "推送方式,1-短信;2-邮件;3-app;4-wechat", requiredMode = Schema.RequiredMode.REQUIRED)
    private Integer pushType;
    @NotBlank(message = "通知推送接收地址 不能为空")
    @Schema(description = "通知推送接收地址", requiredMode = Schema.RequiredMode.REQUIRED)
    private String receiveAddress;
    @NotNull(message = "是否启用不能为空")
    @Schema(description = "是否启用,0-未启用,1-启用", requiredMode = Schema.RequiredMode.REQUIRED)
    private Integer enable;
}

@Schema 注解中参数是否必填使用了一个枚举类 io.swagger.v3.oas.annotations.media.Schema.RequiredMode 这是 @Schema 注解的一个内部类，支持 3 种模式， @Schema 注解中多种属性也采用了枚举类的方式，这是与原来的 @ApiModelPropertity 注解区别比较大的地方。

3.3.3 公共返回参数(包含泛型)

demo-knife4j-openapi3/src/main/java/com/ljq/demo/springboot/knife4j/common/api/ApiResult.java

package com.ljq.demo.springboot.knife4j.common.api;
import io.swagger.v3.oas.annotations.media.Schema;
import lombok.Data;
import org.slf4j.MDC;
import java.util.Map;
/**
 * @Description: 接口返回结果
 * @Author: junqiang.lu
 * @Date: 2020/9/3
 */
@Data
public class ApiResult {
    /**
     * 默认成功结果 key
     */
    public static final String DEFAULT_SUCCESS_KEY = "api.response.success";
    /**
     * 默认成功返回提示信息
     */
    public static final String DEFAULT_SUCCESS_MESSAGE = "SUCCESS";
    /**
     * 默认错误结果 key
     */
    public static final String DEFAULT_ERROR_KEY = "api.response.error";
    /**
     * 默认错误返回提示信息
     */
    public static final String DEFAULT_ERROR_MESSAGE = "ERROR";
    /**
     * 请求 id key
     */
    public static final String REQUEST_ID_KEY = "REQUEST_ID";
    /**
     * 返回结果 key
     */
    @Schema(description = "返回结果 key")
    private String key;
    /**
     * 返回提示信息
     */
    @Schema(description = "返回提示信息")
    private String message;
    /**
     * 返回数据
     */
    private T data;
    /**
     * 额外返回数据
     */
    @Schema(description = "额外返回数据")
    private Map extraDataMap;
    /**
     * 系统当前时间(精确到毫秒)
     */
    @Schema(description = "系统当前时间(精确到毫秒)")
    private Long timestamp = System.currentTimeMillis();
    /**
     * 请求 id
     */
    @Schema(description = "请求 id")
    private String requestId = MDC.get(REQUEST_ID_KEY);
    private ApiResult(){
    }
    /**
     * 构造方法
     *
     * @param key
     * @param message
     * @param data
     * @param extraDataMap
     */
    protected ApiResult(String key, String message, T data, Map extraDataMap) {
        this.key = key;
        this.message = message;
        this.data = data;
        this.extraDataMap = extraDataMap;
    }
    /**
     * 成功
     *
     * @return
     */
    public static  ApiResult success() {
        return success(null,null);
    }
    /**
     * 成功
     *
     * @param data 返回数据
     * @return
     */
    public static  ApiResult success(T data) {
        return success(data, null);
    }
    /**
     * 成功
     *
     * @param data 返回数据
     * @param extraDataMap 额外返回数据
     * @return
     */
    public static  ApiResult success(T data, Map extraDataMap) {
        return new ApiResult<>(DEFAULT_SUCCESS_KEY, DEFAULT_SUCCESS_MESSAGE, data, extraDataMap);
    }
    /**
     * 失败
     *
     * @return
     */
    public static  ApiResult fail() {
        return fail(DEFAULT_ERROR_KEY, DEFAULT_ERROR_MESSAGE, null, null);
    }
    /**
     * 失败
     *
     * @param responseKey 返回结果 key
     * @param message 返回提示信息
     * @return
     */
    public static  ApiResult fail(String responseKey, String message) {
        return fail(responseKey, message, null, null);
    }
    /**
     * 失败
     *
     * @param responseKey 返回结果 Key
     * @param message 返回提示信息
     * @param data 返回数据
     * @param extraDataMap 额外返回数据
     * @return
     */
    public static  ApiResult fail(String responseKey, String message, T data, Map extraDataMap) {
        return new ApiResult<>(responseKey, message, data, extraDataMap);
    }
}

这里需要注意的是公共返回结果类上不能使用 @Schema 注解，尤其是在指定 name 的情况下，这会使生成的接口文档没有对应泛型类的属性，所有的返回结果都是一样的，看不到返回结果具体对象的属性，增加了前后端对接成本，这不符合我们对于接口文档的要求。

于此同时，对于泛型类 data 参数，也不要使用 @Schema 注解，对于没有使用 lombok 插件，而手动书写 getter/setter 的方式，data 的 getter 方法返回结果也必须是 T 而不能是 Object 类型，否则也无法生成对应泛型类的属性文档。

3.4 Controller 控制层示例

demo-knife4j-openapi3/src/main/java/com/ljq/demo/springboot/knife4j/controller/UserPushTypeController.java

package com.ljq.demo.springboot.knife4j.controller;
import com.baomidou.mybatisplus.core.metadata.IPage;
import com.ljq.demo.springboot.knife4j.common.api.ApiResult;
import com.ljq.demo.springboot.knife4j.model.entity.UserPushTypeEntity;
import com.ljq.demo.springboot.knife4j.model.param.userpushtype.*;
import com.ljq.demo.springboot.knife4j.service.UserPushTypeService;
import io.swagger.v3.oas.annotations.Operation;
import io.swagger.v3.oas.annotations.tags.Tag;
import org.springdoc.api.annotations.ParameterObject;
import org.springframework.http.MediaType;
import org.springframework.http.ResponseEntity;
import org.springframework.validation.annotation.Validated;
import org.springframework.web.bind.annotation.*;
import javax.annotation.Resource;
/**
 * 用户消息推送方式
 * 
 * @author junqiang.lu
 * @date 2023-08-15 10:41:29
 */
@RestController
@RequestMapping(value = "/knife4j/user/pushtype")
@Tag(name = "用户消息推送方式控制层")
public class UserPushTypeController {
	@Resource
	private UserPushTypeService userPushTypeService;
    @PostMapping(value = "/add", produces = {MediaType.APPLICATION_JSON_VALUE})
    @Operation(summary = "用户消息推送方式保存(单条)")
    public ResponseEntity> save(@RequestBody @Validated UserPushTypeSaveParam saveParam) {
        return ResponseEntity.ok(userPushTypeService.save(saveParam));
    }
    @GetMapping(value = "/query/info", produces = {MediaType.APPLICATION_JSON_VALUE})
    @Operation(summary = "用户消息推送方式查询详情(单条)")
    public ResponseEntity> info(@Validated @ParameterObject UserPushTypeInfoParam infoParam) {
        return ResponseEntity.ok(userPushTypeService.info(infoParam));
    }
    @GetMapping(value = "/query/page", produces = {MediaType.APPLICATION_JSON_VALUE})
    @Operation(summary = "用户消息推送方式查询列表")
    public ResponseEntity>> list(@Validated @ParameterObject UserPushTypeListParam listParam) {
        return ResponseEntity.ok(userPushTypeService.list(listParam));
    }
    @PutMapping(value = "/update", produces = {MediaType.APPLICATION_JSON_VALUE})
    @Operation(summary = "用户消息推送方式修改(单条)")
    public ResponseEntity update(@RequestBody @Validated UserPushTypeUpdateParam updateParam) {
        return ResponseEntity.ok(userPushTypeService.update(updateParam));
    }
    @DeleteMapping(value = "/delete", produces = {MediaType.APPLICATION_JSON_VALUE})
    @Operation(summary = "用户消息推送方式删除(单条)")
    public ResponseEntity delete(@RequestBody @Validated UserPushTypeDeleteParam deleteParam) {
        return ResponseEntity.ok(userPushTypeService.delete(deleteParam));
    }
}

在 Controller 类中，原来 Swagger 2 的 @Api 注解替换为 @Tag, 原来的 @ApiOperation 注解替换为 @Operation。

在请求头中的参数，例如 GET 请求，如果是一个对象，则需要使用 @ParameterObject 注解，如果不添加，则无法在 Swagger 接口文档界面进行正常请求。

4 升级注意事项(踩坑指南)

4.1 Swagger 2 注解替换

Replace swagger 2 annotations with swagger 3 annotations (it is already included with springdoc-openapi-starter-webmvc-ui dependency). Package for swagger 3 annotations is io.swagger.v3.oas.annotations.
- @Api → @Tag
- @ApiIgnore → @Parameter(hidden = true) or @Operation(hidden = true) or @Hidden
- @ApiImplicitParam → @Parameter
- @ApiImplicitParams → @Parameters
- @ApiModel → @Schema
- @ApiModelProperty(hidden = true) → @Schema(accessMode = READ_ONLY)
- @ApiModelProperty → @Schema
- @ApiOperation(value = "foo", notes = "bar") → @Operation(summary = "foo", description = "bar")
- @ApiParam → @Parameter
- @ApiResponse(code = 404, message = "foo") → @ApiResponse(responseCode = "404", description = "foo")
- This step is optional: Only if you have multiple Docket beans replace them with GroupedOpenApi beans.
  Migrating from SpringFox
  
  4.2 公共返回参数不能使用 @Schema 注解，否则就会只生成一个 Swagger Model
  
  swagger(三)：统一返回结果不显示字段说明
  
  4.3 Get 请求参数前需要添加 @ParamterObject 注解
  
  springdoc-openapi 在 1.6.11 版本中添加了一个配置，可以一键解决不使用 @ParamterObject 注解 Swagger 接口测试不可用的问题，配置如下:
```
springdoc:
  # 默认是false，需要设置为true
  default-flat-param-object: true
```
  然而这么做之后，所有通过 body 传的参数也会变成请求头传递，这只是把问题转移了，并没有从根本上解决问题。
  
  针对这一点，对于想要尝鲜的用户还是要注意书写规范，否则改动量就非常大了。
  
  Knife4j v4.0版本针对参数解析ParameterObject的问题说明
  
  5 使用效果
  
  5.1 导出到 Postman 等测试工具的接口数据地址
```
http://127.0.0.1:9050/v3/api-docs
```
  5.2 Knife4j 导出接口文档
  
  5.3 Knife4j UI 界面
  
  地址:
```
http://127.0.0.1:9050/doc.html
```
  效果图:
  
  5.4 Swagger UI 界面
  
  地址:
```
http://127.0.0.1:9050/swagger-ui/index.html
```
  效果图:
  
  6 推荐参考资料
  
  Knife4j 官方文档: https://doc.xiaominfo.com/docs/quick-start
  
  Springdoc 官方文档: https://springdoc.org
  
  【超详细】springboot + springdoc-openapi + knife4j 集成案例
  
  swagger(三)：统一返回结果不显示字段说明
  
  Knife4j v4.0版本针对参数解析ParameterObject的问题说明
  
  7 Github 源码
  
  Gtihub 源码地址 : https://github.com/Flying9001/springBootDemo/tree/master/demo-knife4j-openapi3
  
  个人公众号:404Code,分享半个互联网人的技术与思考，感兴趣的可以关注.