Spring Boot 3中如何基于HttpExchange接口生成外部API的OpenAPI文档？

以下是具体实现步骤：

1. 为HttpExchange接口添加OpenAPI注解 #

直接在你的HttpExchange接口上标注OpenAPI相关注解，配合Spring 6的@GetExchange/@PostExchange等注解，让SpringDoc识别接口信息：

import io.swagger.v3.oas.annotations.Operation;
import io.swagger.v3.oas.annotations.Parameter;
import io.swagger.v3.oas.annotations.media.Content;
import io.swagger.v3.oas.annotations.media.Schema;
import io.swagger.v3.oas.annotations.responses.ApiResponse;
import io.swagger.v3.oas.annotations.tags.Tag;
import org.springframework.web.service.annotation.GetExchange;
import org.springframework.web.bind.annotation.PathVariable;

@Tag(name = "外部用户API", description = "调用第三方用户服务的接口")
public interface UserExternalApi {

    @Operation(
            summary = "获取单个用户信息",
            description = "根据用户ID调用外部API获取详细信息",
            responses = {
                    @ApiResponse(responseCode = "200", description = "成功获取用户信息",
                            content = @Content(mediaType = "application/json",
                                    schema = @Schema(implementation = UserDto.class))),
                    @ApiResponse(responseCode = "404", description = "用户不存在")
            }
    )
    @GetExchange("/api/users/{userId}")
    UserDto getUserById(@Parameter(description = "目标用户ID") @PathVariable String userId);
}

2. 配置SpringDoc扫描HttpExchange接口 #

在application.yml或application.properties中指定要扫描的包路径，确保SpringDoc能检测到你的HttpExchange接口：

springdoc:
  packages-to-scan: com.yourpackage.external.api # 替换为你的HttpExchange接口所在包

如果需要更灵活的配置，可以创建配置类手动注册接口分组：

import io.swagger.v3.oas.models.OpenAPI;
import io.swagger.v3.oas.models.info.Info;
import org.springdoc.core.models.GroupedOpenApi;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;

@Configuration
public class OpenApiConfig {

    @Bean
    public GroupedOpenApi externalApiGroup() {
        return GroupedOpenApi.builder()
                .group("external-apis")
                .packagesToScan("com.yourpackage.external.api")
                .build();
    }

    @Bean
    public OpenAPI customOpenAPI() {
        return new OpenAPI()
                .info(new Info()
                        .title("外部API调用文档")
                        .version("1.0")
                        .description("项目中调用的第三方服务API文档"));
    }
}

3. 为请求/响应模型添加Schema注解 #

给外部API对应的请求、响应实体类添加@Schema注解，完善文档中的模型结构信息：

import io.swagger.v3.oas.annotations.media.Schema;

@Schema(name = "用户信息DTO", description = "外部API返回的用户数据结构")
public class UserDto {

    @Schema(description = "用户ID", example = "1001")
    private String userId;

    @Schema(description = "用户名", example = "张三")
    private String username;

    // 省略getter/setter方法
}

4. 验证文档生成 #

启动Spring Boot项目后，访问http://localhost:8080/swagger-ui.html（端口根据你的项目配置调整），在页面中找到对应的分组（比如上面配置的external-apis），就能看到生成的外部API调用文档，包含接口路径、参数说明、响应模型等完整信息。

内容的提问来源于stack exchange，提问作者Wee