Swagger 模块 ¶

说明 ¶

WARNING

注意：所使用的的是Swagger3(SpringDoc)，不支持Swagger2相关的注解，因为Swagger2(SpringFox)已经在17年停止维护了，最新的Spirng Boot版本与Swagger2已经有不兼容的问题，所以为了后期更少出现问题，建议直接使用Swagger3(SpringDoc)

基于Knife4j+Swagger3进行实现，Knife4j是一个集Swagger2 和 OpenAPI3 为一体的增强解决方案，同时对接口文档分组做了些增强。

Swagger3注解对照表 ¶

swagger2	Swagger3	说明
@Api	@Tag(name= “接口类描述”)	Controller 类上
@ApiOperation	@Operation(summary =“接口方法描述”)	Controller 方法上
@ApiImplicitParams	@Parameters	Controller方法上
@ApiImplicitParam	@Parameter(description=“参数描述”)	Controller 方法上
@ApiParam	@Parameter(description=“参数描述”)	Controller 方法参数上
@ApiIgnore	@Parameter(hidden = true) 或 @Operation(hidden = true) 或 @Hidden	参数上
@ApiModel	@Schema(title = "实体类标题")	对象上
@ApiModelProperty	@Schema(description= "字段描述")	对象属性上
-	@ParameterObject	Controller 方法参数上，使用@ParameterObject 注解修饰的请求参数对象，会将对象的每个字段添加为单独的请求参数

使用样例 ¶

Controller ¶

java

@Tag(name ="系统参数")
@RestController
@RequestMapping("/system/param")
@RequiredArgsConstructor
public class SystemParamController {
    private final SystemParamService systemParamService;
    
    @Operation(summary = "添加")
    @PostMapping("/add")
    public ResResult<Void> add(@RequestBody SystemParameterParam param){
        systemParamService.add(param);
        return Res.ok();
    }
    
    @Operation(summary = "分页")
    @GetMapping("/page")
    public ResResult<PageResult<SystemParameterDto>> page(@ParameterObject PageParam pageParam,
                                                          @ParameterObject SystemParameterParam param){
        return Res.ok(systemParamService.page(pageParam,param));
    }
}

实体类 ¶

java

@EqualsAndHashCode(callSuper = true)
@Data
@Accessors(chain = true)
@Schema(title = "系统参数")
public class SystemParameterDto extends BaseDto {

    @Schema(description= "参数名称")
    private String name;

    @Schema(description= "参数键名")
    private String paramKey;
}

knife4j配置 ¶

项目Swagger的UI使用的是knife4j提供的图形化界面，同时后端的接口文档使用的是knife4j，可以使用knife4j提供的各种特性，具体使用见knife4j配置，增强特性

yaml

# Swagger 增强配置
knife4j:
  # 是否开启增强模式
  enable: true
  basic:
    enable: true
    username: admin
    password: 123123

自定义配置 ¶

TIP

对多文档分组进行增强，支持一个分组文档扫描多个包，原理是通过Spring的动态注册Bean和数据绑定功能，在容器Bean初始化之前把GroupedOpenApi（相当于Swagger2的Docket）注入到Spring容器中来实现。数据权限.

yaml

# 项目配置
bootx:
  common:
    swagger:
      # 是否启用，生产环境推荐关闭
      enabled: true
      author: bootx
      version: 1.x.x
      title: bootx开发平台单体版
      description: bootx-platform开发平台单体版
      # 多模块扫包
      base-packages:
        "[基础API]": cn.bootx.platform.baseapi
        "[IAM认证管理]": cn.bootx.platform.iam
        "[消息服务]": cn.bootx.platform.notice
        "[演示模块]": cn.bootx.platform.demo
        # 支持一个模块扫描多个包
        "[第三方对接]":
          - cn.bootx.platform.starter.dingtalk
          - cn.bootx.platform.starter.wecom
          - cn.bootx.platform.starter.wechat
        "[自定义starter组件]": cn.bootx.platform.starter