springboot3如何使用swagger和knife4j

背景

knife4j推出来之后以其更适合国人的风格而受欢迎¹。在去年的今日，springboot3推出之后，swagger2完全不适用于这个版本。
这里要改变为spring-doc风格来与之匹配，同时对应的maven/gradle相关依赖也需要进行变更。

变更细节

maven依赖的改变

这里引入依赖的坐标²有了变化，如下面的代码块所示

		<dependency>
            <groupId>com.github.xiaoymin</groupId>
            <artifactId>knife4j-openapi3-jakarta-spring-boot-starter</artifactId>
        </dependency>

这里要注意，spring boot3最低版本jdk要用17，javaee相关的部分将要迁移到jakartaee。

配置的变化

这里相关的spring-doc配置³改为swagger3风格。
其他部分的配置变化如下：

# springdoc-openapi项目配置
springdoc:
  swagger-ui:
    path: /swagger-ui.html
    tags-sorter: alpha
    operations-sorter: alpha
  api-docs:
    path: /v3/api-docs
  group-configs:
    - group: 'default'
      paths-to-match: '/**'
      packages-to-scan: com.xiaominfo.knife4j.demo.web
# knife4j的增强配置，不需要增强可以不配
knife4j:
  enable: true
  setting:
    language: zh_cn

这里knife4j部分是做增强的，参考官方文档⁴进行配置。

类中使用变化

Controller层

这里@Api和@ApiOperation被弃用，使用对应的注解@Tags和@Operation，具体样例如下：

@RestController
@RequestMapping("body")
@Tag(name = "body参数")
public class BodyController {

   @Operation(summary = "普通body请求")
   @PostMapping("/body")
   public ResponseEntity<FileResp> body(@RequestBody FileResp fileResp){
       return ResponseEntity.ok(fileResp);
   }

   @Operation(summary = "普通body请求+Param+Header+Path")
   @Parameters({
           @Parameter(name = "id",description = "文件id",in = ParameterIn.PATH),
           @Parameter(name = "token",description = "请求token",required = true,in = ParameterIn.HEADER),
           @Parameter(name = "name",description = "文件名称",required = true,in=ParameterIn.QUERY)
   })
   @PostMapping("/bodyParamHeaderPath/{id}")
   public ResponseEntity<FileResp> bodyParamHeaderPath(@PathVariable("id") String id,@RequestHeader("token") String token, @RequestParam("name")String name,@RequestBody FileResp fileResp){
       fileResp.setName(fileResp.getName()+",receiveName:"+name+",token:"+token+",pathID:"+id);
       return ResponseEntity.ok(fileResp);
   }
}

Bean上注解变化

Bean上的@ApiModel和@ApiModelProperty都改为@Schema注解了，并且有些属性已经过时。代码块如下

package com.oschina.xf.modules.ums.model;



import com.mybatisflex.annotation.Id;
import com.mybatisflex.annotation.KeyType;
import com.mybatisflex.annotation.Table;
import io.swagger.v3.oas.annotations.media.Schema;
import lombok.Data;
import lombok.EqualsAndHashCode;

import java.io.Serializable;
import java.util.Date;

/**
 * <p>
 * 后台用户表
 * </p>
 *
 * @author macro
 * @since 2020-08-21
 */
@Data
@EqualsAndHashCode(callSuper = false)
@Table("ums_admin")
@Schema(name="UmsAdmin对象", description="后台用户表")
public class UmsAdmin implements Serializable {

    private static final long serialVersionUID=1L;

    @Id(value = "id", keyType = KeyType.Auto)
    private Long id;

    private String username;

    private String password;

    @Schema(description = "头像")
    private String icon;

    @Schema(description = "邮箱")
    private String email;

    @Schema(description = "昵称")
    private String nickName;

    @Schema(description = "备注信息")
    private String note;

    @Schema(description = "创建时间")
    private Date createTime;

    @Schema(description = "最后登录时间")
    private Date loginTime;

    @Schema(description = "帐号启用状态：0->禁用；1->启用")
    private Integer status;


}

总结

由于springboot3兼容的swagger要升到3，所以，需要knife4j要升级到jakarta对应的依赖版本来进行替换处理。

---

1. knife4j使用 ↩︎

2. 快速开始knife4j ↩︎

3. springdoc说明 ↩︎

4. knife4j配置 ↩︎