SpringBoot集成SpringDoc

一、序

其实我一直比较喜欢的文档是knife4j，之前一直又推文说SpringDoc好，所以打算尝试下。
SpringBoot版本：2.7.0
SpringDoc版本：1.6.10 放行："/v3/api-docs/**", "/swagger-ui/**"
Knife4j版本：3.0.3 放行："/doc.html", "/webjars/**"

二、依赖集成

<springdoc.version>1.6.10</springdoc.version>

<dependency>
   <groupId>org.springdoc</groupId>
   <artifactId>springdoc-openapi-ui</artifactId>
   <version>${springdoc.version}</version>
</dependency>

访问路径：SpringDoc访问路径

三、配置SpringDoc

3.1 代码注释

@RestController
@Tag(name = "auth: 安全模块")
public class AuthController {
    @Operation(summary = "验证码")
    @GetMapping("captcha")
    public CaptchaVo captcha() {
        SpecCaptcha specCaptcha = new SpecCaptcha(130, 48, 4);
        String verCode = specCaptcha.text().toLowerCase();
        String uuid = IdUtil.fastSimpleUUID();
        RedisUtil.set(RedisKeyConst.CAPTCHA + uuid, verCode, 180);

        return new CaptchaVo(uuid, specCaptcha.toBase64());
    }

    @Operation(summary = "登录")
    @PostMapping("login")
    public void login() {

    }
}

@Getter
@Setter
@Schema(description = "验证码")
public class CaptchaVo implements Serializable {
    @Schema(description = "uuid")
    private String uuid;
    @Schema(description = "验证码图片base64")
    private String base64;
}

3.2 配置

@Configuration
public class SwaggerConfig {

    @Bean
    public OpenAPI springShopOpenApi() {
        final String loginToken = "BearerAuth";
        return new OpenAPI().info(new Info().title("Simple Boot API")
                        .description("SpringBoot基础框架")
                        .version("v1.0.0")).externalDocs(new ExternalDocumentation()
                        .description("SpringBoot基础框架")
                        .url("http://127.0.0.1:8088"))
                .components(new Components().addSecuritySchemes(loginToken, new SecurityScheme()
                        .type(SecurityScheme.Type.HTTP).scheme("bearer").bearerFormat("JWT")
                        .in(SecurityScheme.In.HEADER)
                        .name(loginToken)))
                .addSecurityItem(new SecurityRequirement().addList(loginToken));
    }

    @Bean
    public GroupedOpenApi systemApi() {
        return GroupedOpenApi.builder().group("System系统模块")
                .pathsToMatch("/system/**")
                .build();
    }

    @Bean
    public GroupedOpenApi authApi() {
        return GroupedOpenApi.builder().group("Auth权限模块")
                .pathsToMatch("/captcha", "/login")
                .build();
    }

}

3.3 放行接口

首先你需要在你的权限框架放行路径/swagger-ui/**，不然你没办法访问。

3.4 配置文件配置

application.yml

springdoc:
    swagger-ui:
        # 禁止默认路径
        disable-swagger-default-url: true

上述配置是为了关闭自带的路径，如不配置会出现以下页面：

假设你之前没有进行如上配置，你配置之后一定要清缓存、清缓存、清缓存，不然不会生效，还以为自己配错了。

3.5 放行文档数据

这一步其实和3.1是一模一样的，之所以分开写是为了让踩坑的小伙伴知道具体啥情况

完成上述两边，在清缓存之后，你大概会看到一个空白页：

假设你已经存在接口，并标注了注释，此时仍不会出来数据，原因就是接口数据的路径被拦截了，可以F12一个个看看，返回不是200的，放行一下/v3/api-docs/**就好了。

至此，SpringDoc集成成功。

四、集成Knife4j

因为我一直比较喜欢Knife4j的样式，所以参照Knife4j官网的配置加了些。

4.1 添加依赖

<!--引入Knife4j的官方ui包,OpenAPI3建议使用springdoc-openapi项目-->
<dependency>
  <groupId>com.github.xiaoymin</groupId>
  <artifactId>knife4j-springdoc-ui</artifactId>
  <version>3.0.3</version>
</dependency>

4.2 放行接口

"/doc.html", "/webjars/**"