springboot3如何使用swagger和knife4j
背景
knife4j推出来之后以其更适合国人的风格而受欢迎1。在去年的今日,springboot3推出之后,swagger2完全不适用于这个版本。
这里要改变为spring-doc风格来与之匹配,同时对应的maven/gradle相关依赖也需要进行变更。
变更细节
maven依赖的改变
这里引入依赖的坐标2有了变化,如下面的代码块所示
<dependency>
<groupId>com.github.xiaoymin</groupId>
<artifactId>knife4j-openapi3-jakarta-spring-boot-starter</artifactId>
</dependency>
这里要注意,spring boot3最低版本jdk要用17,javaee相关的部分将要迁移到jakartaee。
配置的变化
这里相关的spring-doc配置3改为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部分是做增强的,参考官方文档4进行配置。
类中使用变化
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对应的依赖版本来进行替换处理。