SpringBoot2.7集成Swagger3

Swagger2已经在17年停止维护了，取而代之的是 Swagger3（基于openApi3），所以新项目要尽量使用Swagger3.

Open API

OpenApi是业界真正的 api 文档标准，其是由 Swagger 来维护的，并被linux列为api标准，从而成为行业标准。

Swagger

swagger 是一个 api 文档维护组织，后来成为了 Open API 标准的主要定义者，现在最新的版本为17年发布的Swagger3（Open Api3）。国内绝大部分人还在用过时的swagger2（17年停止维护并更名为swagger3）。swagger2的包名为 io.swagger，而swagger3的包名为 io.swagger.core.v3。

SpringFox

SpringFox是 spring 社区维护的一个项目（非官方），帮助使用者将 swagger2 集成到 Spring 中。常常用于 Spring 中帮助开发者生成文档，并可以轻松的在spring boot中使用。

SpringDoc

SpringDoc也是 spring 社区维护的一个项目（非官方），帮助使用者将 swagger3 集成到 Spring 中。

也是用来在 Spring 中帮助开发者生成文档，并可以轻松的在spring boot中使用。

Swagger3与 Swagger2注解对比使用

使用 swagger3 注解代替 swagger2 的（为可选项）

|-------------------------------------------------------------|-----------------------------|-----------------------------------------------|
| Swagger3 | Swagger2 | 注解说明 |
| @Tag(name = "接口类描述") | @Api | Controller 类 |
| @Operation(summary ="接口方法描述") | @ApiOperation | Controller 方法 |
| @Parameters | @ApiImplicitParams | Controller 方法 |
| @Parameter(description="参数描述") | @ApiImplicitParam @ApiParam | Controller 方法上 @Parameters 里 Controller 方法的参数 |
| @Parameter(hidden = true) @Operation(hidden = true) @Hidden | @ApiIgnore | 排除或隐藏api |
| @Schema | @ApiModel @ApiModelProperty | DTO实体 DTO实体属性 |

Swagger2 的注解命名以易用性切入，全是 Api 开头，在培养出使用者依赖注解的习惯后，Swagger 3将注解名称规范化，工程化。

MybatisPlus生成Swagger3注解

参考文档:代码生成器（新） | MyBatis-Plus

java 复制代码

public class CodeGenerator {

    public static void main(String[] args) {
        // 配置文档: https://baomidou.com/pages/981406/#%E6%95%B0%E6%8D%AE%E5%BA%93%E9%85%8D%E7%BD%AE-datasourceconfig
        String projectPath = System.getProperty("user.dir");
        FastAutoGenerator.create("url", "username", "password")
                .globalConfig(builder -> {
                    builder.author("Cloud") // 设置作者
                            .enableSwagger() // 开启 swagger 模式
                            .enableSpringdoc() // 使用swagger3
                            .outputDir(projectPath + "/generator/src/main/java"); // 指定输出目录
                })
                .dataSourceConfig(builder -> builder.typeConvertHandler((globalConfig, typeRegistry, metaInfo) -> {
                    int typeCode = metaInfo.getJdbcType().TYPE_CODE;
                    if (typeCode == Types.SMALLINT || typeCode == Types.BIT || typeCode == Types.TINYINT) {
                        // 自定义类型转换
                        return DbColumnType.INTEGER;
                    }
                    return typeRegistry.getColumnType(metaInfo);

                }))
                .packageConfig(builder -> {
                    builder.parent("com.wkt.server") // 设置父包名
                            .moduleName("system") // 设置父包模块名
                            .pathInfo(Collections.singletonMap(OutputFile.xml, projectPath + "/generator/src/main/resources/mapper/")); // 设置mapperXml生成路径
                })
                .strategyConfig(builder -> {
                    builder.addInclude("^.*") // 设置需要生成的表名
                            .addTablePrefix("t_") // 设置过滤表前缀
                            // Entity策略配置
                            .entityBuilder()
                            .enableLombok() // 启用lombok
                            .enableFileOverride() // 每次生成覆盖原文件
                            // Mapper策略配置
                            .mapperBuilder()
                            .enableFileOverride()
                            // Service策略配置
                            .serviceBuilder()
                            .enableFileOverride()
                            .formatServiceFileName("%sService") // 格式为UserService
                            // Controller策略配置
                            .controllerBuilder()
                            .enableFileOverride()
                            .enableRestStyle(); // 生成@RestController

                })
                .templateEngine(new FreemarkerTemplateEngine()) // 使用Freemarker引擎模板，默认的是Velocity引擎模板
                .execute();
    }
}

生成代码:

Controller注解示例:

java 复制代码

@RestController
@RequestMapping("/admin/config")
@Tag(name = "配置管理")
public class ConfigController extends BaseController {
    @Autowired
    private ConfigService configService;

    @Operation(summary = "根据key查询配置")
    @GetMapping("getByKey")
    public Result<Config> getByKey(String key) {
        return resultOk(configService.getById(key));
    }
}

实体类注解示例:

java 复制代码

@Getter
@Setter
@Schema(description = "配置表")
public class Config implements Serializable {

    private static final long serialVersionUID = 1L;

    @TableId("config_key")
    private String configKey;

    private String configValue;

    @Schema(description = "备注")
    private String remark;

    @Schema(description = "配置类型")
    private Integer type;
}

SpringBoot对应Swagger版本参考: Springboot ✚ Swagger各版本整理_swagger版本-CSDN博客

SpringBoot2.7集成knife4j

依赖:

XML 复制代码

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

配置类

java 复制代码

@Configuration
public class SwaggerConfig {
    @Bean
    public OpenAPI openAPI() {
        StringBuilder desc = new StringBuilder();
        desc.append("后台管理系统接口文档");

        return new OpenAPI()
                .info(new Info()
                        .title("后台管理系统 - 接口文档")
                        .description(desc.toString())
                        .version("V1.0")
                        .contact(new Contact().name("Cloud"))
                );
    }

    @Bean
    public GroupedOpenApi adminApi() {
        return GroupedOpenApi.builder()
                .group("后台接口")
                .packagesToScan("你的包名")
                .build();
    }
}

如果你要用对象来接收get请求参数，需要在yml里面加个配置，不然文档显示会有问题

java 复制代码

springdoc:
  # 处理get请求用对象接收时文档显示不正确
  default-flat-param-object: true

ps:这个配置当前有点问题，需要等springdoc解决这个bug,参考

4.3.0版本解析出来的content-type 为application/x-www-form-urlencoded 实际上是application/json · Issue #I8AFNB · 萧明/knife4j - Gitee.com

Knife4j v4.0版本针对参数解析ParameterObject的问题说明 | Knife4j