SpringDoc OpenAPI 中如何动态注册未直接引用的Schema

在基于SpringDoc OpenAPI的项目开发中，我们经常会遇到需要动态注册Schema的需求，特别是那些没有被控制器直接引用的DTO类。本文将详细介绍如何通过编程方式实现这一需求。

问题背景

在实现RESTful API时，我们通常会定义一些通用的错误响应DTO，比如符合RFC 9457标准的ProblemDetail。这些DTO可能不会直接在控制器方法中被引用为返回类型，而是通过OperationCustomizer动态添加到各个操作的响应中。

这种情况下，OpenAPI文档生成器不会自动将这些DTO注册为可用的Schema组件，导致在动态添加响应时出现引用错误。

解决方案

SpringDoc OpenAPI提供了ModelConverters工具类，可以帮助我们手动解析和注册这些Schema。以下是具体实现步骤：

1. 定义DTO类

首先定义一个标准的ProblemDetailDTO类，使用@Schema注解进行描述：

@Schema(
    name = "ProblemDetail",
    description = "Representation of an RFC 9457 problem detail."
)
data class ProblemDetailDto(
    @Schema(
        description = "The URI reference that identifies the problem type."
    )
    val type: URI,
    
    @Schema(
        description = "The HTTP status code generated by the origin server.",
        minimum = "100",
        maximum = "599"
    )
    val status: Int
)

2. 配置OpenAPI

创建一个配置类，使用ModelConverters手动解析并注册Schema：

@Configuration
class OpenApiConfig {

    @Bean
    fun modelConverters(): ModelConverters = ModelConverters.getInstance(true)

    @Bean
    fun openApi(modelConverters: ModelConverters): OpenAPI {
        return OpenAPI().apply {
            components = Components().apply {
                addSchemas(
                    "ProblemDetail",
                    modelConverters
                        .resolveAsResolvedSchema(
                            AnnotatedType(ProblemDetailDto::class.java)
                            .resolveAsRef(false)
                        ).schema
                )
            }
        }
    }
}

3. 动态添加响应

在OperationCustomizer中，现在可以安全地引用已注册的Schema了：

operation.responses.addApiResponse(
    statusCode,
    ApiResponse().apply {
        description = reasonPhrase
        content = Content().addMediaType(
            APPLICATION_PROBLEM_JSON_VALUE,
            MediaType().schema(
                Schema<Any>().apply {
                    `$ref` = "#/components/schemas/ProblemDetail"
                }
            )
        )
    }
)

技术要点

1. ModelConverters：SpringDoc提供的模型转换工具，可以将Java/Kotlin类转换为OpenAPI Schema定义。

2. AnnotatedType：包装目标类类型，可以携带额外的注解信息。

3. resolveAsRef(false)：指示解析器不要将结果作为引用返回，而是返回完整的Schema定义。

4. 组件注册：通过OpenAPI对象的components属性显式添加Schema定义。

最佳实践

1. 对于通用的响应DTO，建议集中在一个配置类中注册。

2. 考虑创建自定义注解来标记需要手动注册的DTO类。

3. 可以扩展此方案，实现自动扫描特定包下所有标记类并自动注册。

4. 在微服务架构中，可以将这些通用Schema定义提取到共享库中。

通过这种方式，我们既保持了代码的整洁性，又确保了OpenAPI文档的完整性，为API消费者提供了准确的接口描述。