迁移 Swagger 到 OpenApi 需要替代

Question

您好，我将应用程序从 SwaggerFox 迁移到 OpenApi。 我有很多值对象，例如：

data class UserId(@JsonValue val value: UUID) 

在 Swagger 配置中我有一个配置：

override fun Docket.additionalConfiguration(): Docket =
        directModelSubstitute(type.java, String::class.java)(UserId::class, UUID::class)

在 swagger-ui 中我有：

"userId": "string"

现在，当我迁移到 openapi 时，同一个模型看起来有所不同：

"userId": {
    "value": "string"
  }

open api 中有配置值对象的选项吗？

Answer 1

在 OpenAPI 中，您可以使用 @Schema 注释来自定义模型的表示，包括值对象。您可以使用此注释来指定模型的格式、示例和其他属性。对于您的具体情况，您可以使用 @Schema 注释自定义 UserId 类以实现所需的表示形式。例如，您可以在 UserId 类上使用 @Schema 注释，如下所示：

import com.fasterxml.jackson.annotation.JsonValue
import io.swagger.v3.oas.annotations.media.Schema
import java.util.UUID

data class UserId(@JsonValue val value: UUID)

并且在您的 OpenAPI 配置中，您可以使用 @Schema 注释来配置 UserId 类的表示：

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

@Schema(substitutes = UserId::class)
data class UserIdSchema(val value: String)

这里，@Schema(substitutes = UserId::class) 表示应使用 UserIdSchema 来替代 OpenAPI 文档中的 UserId。 UserIdSchema 类有一个 String 类型的属性值，这正是您在 OpenAPI 文档中想要的。

注意： 确保将 UserIdSchema 替换为代表 UserId 类的 OpenAPI 文档的相应类名称。