如何使用 @Schema 注解处理 OpenAPI 3.0 中的空值和引用对象？

使用 @Schema 注解解决 OpenAPI 3.0 swagger 中的空值和引用对象

在为 RESTful API 生成 OpenAPI 3.0 文档时，处理具有空值或引用对象的 Java 类可能会令人头疼。本文将探讨如何使用 io.swagger.core.v3 库中的 @Schema 注解来解决此问题。

背景：理解空值和引用对象

OpenAPI 3.0 规范允许定义可为空或包含引用其他对象的模型。在 Swagger 中，$ref 用于引用对象，而 @Schema 注解用于其他配置选项。

解决方法：使用 @Schema 注解

方法 1：使用 anyOf

anyOf 选项允许指定多个模式，Swagger 将从这些模式中选择一个。对于可为空或引用对象的属性，我们可以使用一个空模式和一个引用对象模式：

@Schema(anyOf = {
  @Schema(implementation = Void.class),
  @Schema(implementation = Address.class)
})
private Address address;

方法 2：在引用对象上使用 @Schema(nullable = true)

此方法指示 Swagger 将引用对象的属性标记为可为空：

@Schema(nullable = true)
private Address address;

推荐方法：在父类上使用 @Schema(nullable = true)

对于更灵活的处理，可以在包含空值或引用对象的父类上使用 @Schema(nullable = true)：

@Schema(nullable = true)
public class BaseClass {
  private Object property;
}

该父类上的 @Schema(nullable = true) 将允许其子类接受空值。

代码示例

以 User 类和 Address 类为例，父类为 BaseClass：

public class User extends BaseClass {
  private int age;
}

public class Address extends BaseClass {
  private String city;
}

此时，OpenAPI 3.0 文档将包含：

"components": {
  "schemas": {
    "BaseClass": {
      "properties": {
        "property": {
          "nullable": true
        }
      }
    },
    "User": {
      "allOf": [
        { "$ref": "#/components/schemas/BaseClass" },
        { "properties": { "age": { "type": "integer" } } }
      ]
    },
    "Address": {
      "allOf": [
        { "$ref": "#/components/schemas/BaseClass" },
        { "properties": { "city": { "type": "string" } } }
      ]
    }
  }
}

结论

使用 @Schema 注解可以生成准确 API 的 OpenAPI 3.0 文档。其中，在父类上使用 @Schema(nullable = true) 是一个可重用、灵活的解决方案。

常见问题解答

1. 是否可以在 @Schema 注解中指定空值的默认值？
   否，空值不能指定默认值。

2. anyOf 和 @Schema(nullable = true) 有什么区别？
   anyOf 指定多个模式，而 @Schema(nullable = true) 将属性标记为可为空。

3. 为什么推荐在父类上使用 @Schema(nullable = true)？
   因为它允许子类继承可为空性，并且在处理复杂或嵌套的 API 时更灵活。

4. 除了 nullable 之外，@Schema 注解还有哪些其他有用的选项？
   其他选项包括 required、example 和 description。

5. 如何使用代码片段来演示 @Schema 注解的使用？
   代码片段已包含在文章中，并在适当的位置显示。