springboot学习第8期 - springdoc

SpringDoc 是专为 Spring Boot 设计的「现代化 API 文档自动生成器」，基于 OpenAPI 3 规范，可 0 配置生成 Swagger-UI、JSON、YAML 接口文档，用来替代早已停止维护的 SpringFox（Swagger2）

导入依赖

xml 复制代码

<dependency>
  <groupId>org.springdoc</groupId>
  <artifactId>springdoc-openapi-starter-webmvc-ui</artifactId>
  <version>2.8.9</version>
</dependency>

接口文档展示

然后访问 http://localhost:8080/swagger-ui/index.html 即可展示接口文档：

示json格式：http://localhost:8080/v3/api-docs

下载yaml格式：http://localhost:8080/v3/api-docs.yaml

如果自定义了 ApiResponse 并且使用 ResponseBodyAdvice 进行转换，则需要 ResponseBodyAdvice 放过 SpringDoc 接口 ↓

java 复制代码

@Override
public boolean supports(MethodParameter returnType, Class<? extends HttpMessageConverter<?>> converterType) {
    // 不拦截 springdoc 请求
    return !returnType.getDeclaringClass().getPackageName()
    .startsWith("org.springdoc");
}

配置接口文档元信息

java 复制代码

@Configuration
public class SpringDocConfig {

    @Bean
    public OpenAPI openAPI() {
        return new OpenAPI()
                .info(new Info()
                        .title("用户中心 API")
                        .version("1.0.0")
                        .description("基于 Spring Boot 3 的用户中心")
                        .contact(new Contact().name("技术支持").email("dev@xxx.com"))
                        .license(new License().name("Apache 2.0").url("http://www.apache.org/licenses/LICENSE-2.0")))
                .externalDocs(new ExternalDocumentation()
                        .description("项目 Wiki")
                        .url("https://wiki.xxx.com"));
    }
}

接口调试

可以直接在 swagger ui 界面调试接口：

配合spring security

如果是基于spring security，还需要额外的配置。

首先需要放行 swagger 相关的接口：

java 复制代码

@Bean
public SecurityFilterChain filterChain(HttpSecurity http) throws Exception {
    return http
    .csrf(AbstractHttpConfigurer::disable)
    .sessionManagement(sm -> sm.sessionCreationPolicy(SessionCreationPolicy.STATELESS))
    .formLogin(AbstractHttpConfigurer::disable)
    .httpBasic(AbstractHttpConfigurer::disable)
    .authorizeHttpRequests(authorize -> authorize
       .requestMatchers("/api/auth/**").permitAll()
       .requestMatchers("/swagger-ui/**", "/v3/api-docs/**", "/swagger-ui.html").permitAll()   // 新增
       .anyRequest().authenticated()
      )
    .addFilterBefore(jwtFilter, UsernamePasswordAuthenticationFilter.class)
    .exceptionHandling(exceptionHandling -> exceptionHandling.authenticationEntryPoint(new AuthenticationEntryPointImpl()))
    .cors(cors -> cors.configurationSource(corsConfigurationSource()))
    .build();
}

JwtFilter也需要放行这些接口：

java 复制代码

@Override
protected boolean shouldNotFilter(HttpServletRequest request) {
// 这些路径不走 JwtFilter
return pathMatcher.match("/api/auth/**", request.getServletPath()) ||
    pathMatcher.match("/swagger-ui/**", request.getServletPath()) ||    // 新增
    pathMatcher.match("/v3/api-docs/**", request.getServletPath()) ||   // 新增
    pathMatcher.match("/swagger-ui.html", request.getServletPath());    // 新增
}

由于增加了spring securty 和 Jwt 认证，那么需要认证的接口如果不传递token是无法访问资源的，那么如果在 swagger ui 输入 token 呢，可以增加以下配置：

java 复制代码

@Configuration
public class SpringDocConfig {

    @Bean
    public OpenAPI openAPI() {
        return new OpenAPI()
        .info(new Info()
              .title("用户中心 API")
              .version("1.0.0")
              .description("基于 Spring Boot 3 的用户中心")
              .contact(new Contact().name("技术支持").email("dev@xxx.com"))
              .license(new License().name("Apache 2.0").url("http://www.apache.org/licenses/LICENSE-2.0")))
        .externalDocs(new ExternalDocumentation()
                      .description("项目 Wiki")
                      .url("https://wiki.xxx.com"))
        // 增加以下配置 ↓↓↓↓
        .components(new Components()
                    .addSecuritySchemes("bearerAuth",
                                        new SecurityScheme()
                                        .type(SecurityScheme.Type.HTTP)
                                        .scheme("bearer")
                                        .bearerFormat("JWT")))
        // 默认全局生效
        .addSecurityItem(new SecurityRequirement().addList("bearerAuth"));
    }

}

这时候 swagger ui 会新增一个认证按钮，可以输入token：

然后就可以调用认证接口：

常用注解

@Tag - 接口分组

java 复制代码

@RestController
@RequestMapping("/api/user")
@RequiredArgsConstructor
@Tag(name = "User", description = "User API")   // 关键
public class UserController {

    private final UserRepository userRepository;

    @GetMapping
    public List<User> getUsers() {
        return userRepository.findAll();
    }

}

@Operation -- 接口描述

java 复制代码

@RestController
@RequestMapping("/api/user")
@RequiredArgsConstructor
@Tag(name = "User", description = "User API")
public class UserController {

    private final UserRepository userRepository;

    @GetMapping
    @Operation(summary = "查询所有用户", description = "查询所有用户 details")  // 关键
    public List<User> getUsers() {
        return userRepository.findAll();
    }

}