知識庫 / JSON / Jackson RSS 訂閱

4.2. 高級配置

在本節中，我們將使用我們的 AdvancedArticle 類：

public class AdvancedArticle {
    private UUID id;
    private String title;
    private String content;
    @AllowedTypes({Timestamp.class, String.class, Date.class})
    private Object createdAt;
    private Area area;
    // getters and setters omitted 
}

高級配置是定製 JSON Schema 生成的終極手段。它特別適用於我們需要通過配置無法提供的屬性的情況：

configBuilder.forFields()
  .withInstanceAttributeOverride((node, field, context) -> node.put("readOnly", field.getDeclaredType().isInstanceOf(UUID.class)));

在這裏，我們為每個屬性都添加了 readOnly 屬性。 默認值為 false，除非是 UUID 類。

{
    "id":{
        "type":"string",
        "format":"uuid",
        "readOnly":true
    },
    "title":{
        "type":"string",
        "readOnly":false
    }
}

另一個有趣的配置選項是能夠在給定字段中指定允許的類型。在我們的 AdvancedArticle 類中，createdAt 屬性同時接受 Date 和 Timestamp 類型：

configBuilder.forFields()
  .withTargetTypeOverridesResolver(field -> Optional.ofNullable(field.getAnnotationConsideringFieldAndGetterIfSupported(AllowedTypes.class))
    .map(AllowedTypes::value)
    .map(Stream::of)
    .map(stream -> stream.map(subtype -> field.getContext().resolve(subtype)))
    .map(stream -> stream.collect(Collectors.toList()))
    .orElse(null));

在底層，TargetTypeOverride 類會處理所有標記為 @AllowedTypes 的字段。然後，它會將這些類型添加到生成的 createdAt 屬性中：

{
    "createdAt":{
        "anyOf":[
            {
                "type":"object",
                "properties":{
                    "nanos":{
                        "type":"integer",
                        "format":"int32",
                        "readOnly":false
                    }
                },
                "readOnly":false
            },
            {
                "type":"string",
                "format":"date-time",
                "readOnly":false
            }
        ]
    }
}

如我們所見，結果的聯合類型由 anyOf 屬性指定。

請記住，配置的可能性是無限的。我們甚至可以添加 自定義類型定義 或 自定義屬性定義。 關鍵在於我們選擇哪種程度的自定義來滿足我們的需求。

5. 模塊

Java JSON Schema Generator 允許我們通過 模塊 將配置項進行分組。 我們可以通過實現 Module 接口 來創建自己的模塊。 在下一部分，我們將看到如何使用一些 內置模塊。 我們將探索 Jackson 和 Jakarta Validation 模塊。

5.1. Jackson

Jackson 模塊 通過處理 Jackson 註解來生成 JSON Schema 配置。 讓我們考慮我們的 Person 類：

class Person {

    @JsonProperty(access = JsonProperty.Access.READ_ONLY)
    UUID id;

    @JsonProperty(access = JsonProperty.Access.READ_WRITE, required = true)
    String name;

    @JsonProperty(access = JsonProperty.Access.READ_WRITE, required = true)
    String surname;

    @JsonProperty(access = JsonProperty.Access.READ_WRITE, required = true)
    Address address;

    @JsonIgnore
    String fullName;

    @JsonProperty(access = JsonProperty.Access.READ_ONLY)
    Date createdAt;

    @JsonProperty(access = JsonProperty.Access.READ_WRITE)
    List<Person> friends;
    //getters and setters omitted
}

讓我們將 JacksonModule 添加到我們的 SchemaGeneratorConfigBuilder 中：

JacksonModule module = new JacksonModule(RESPECT_JSONPROPERTY_REQUIRED);
SchemaGeneratorConfigBuilder configBuilder = new SchemaGeneratorConfigBuilder(DRAFT_2020_12, PLAIN_JSON).with(module)
  .with(EXTRA_OPEN_API_FORMAT_VALUES);

SchemaGenerator generator = new SchemaGenerator(configBuilder.build());
JsonNode jsonSchema = generator.generateSchema(Person.class);

該模塊接受某些選項以進行進一步自定義。 RESPECT_JSONPROPERTY_REQUIRED 選項指示模塊應在模式的 readOnly 字段生成過程中考慮 JsonProperty.Access。

生成的模式已正確設置 required 和 readOnly 字段：

{
    "type":"object",
    "properties":{
        "createdAt":{
            "type":"string",
            "format":"date-time",
            "readOnly":true
        },
        "friends":{
            "type":"array",
            "items":{
                "$ref":"#"
            }
        },
        "id":{
            "type":"string",
            "format":"uuid",
            "readOnly":true
        }
    },
    "required":[
        "address",
        "name",
        "surname"
    ]
}

未註釋的屬性和帶有@JsonIgnore註解的屬性將被忽略。 嵌套的Address類字段以及friends屬性的遞歸模式均得到正確引用。

5.2. Jakarta Validation

Jakarta Validation 模塊 從 jakarta.validation.constraints 註解生成模式配置。 讓我們為 Person 類進行裝飾：

class Person {

    @NotNull
    UUID id;

    @NotNull
    String name;

    @NotNull
    @Email
    @Pattern(regexp = "\\b[A-Za-z0-9._%+-]+@baeldung\\.com\\b")
    String email;

    @NotNull
    String surname;

    @NotNull
    Address address;

    @Null
    String fullName;

    @NotNull
    Date createdAt;

    @Size(max = 10)
    List<Person> friends;
    //getters and setters omitted

}

接下來，讓我們配置 JakartaValidationModule：

JakartaValidationModule module = new JakartaValidationModule(NOT_NULLABLE_FIELD_IS_REQUIRED, INCLUDE_PATTERN_EXPRESSIONS);
SchemaGeneratorConfigBuilder configBuilder = new SchemaGeneratorConfigBuilder(DRAFT_2020_12, PLAIN_JSON).with(module);

SchemaGenerator generator = new SchemaGenerator(configBuilder.build());
JsonNode jsonSchema = generator.generateSchema(Person.class);

模塊可以選擇通過其 forValidationGroups() 方法傳遞驗證組。

NOT_NULLABLE_FIELD_IS_REQUIRED 選項使帶有 @NotNull 註解的字段強制為必填項。 藉助 INCLUDE_PATTERN_EXPRESSIONS，生成的模式包含所有帶有 @Pattern 註解的屬性的模式字段。

{
    "type":"object",
    "properties":{
        "createdAt":{
            "type":"string"
        },
        "email":{
            "type":"string",
            "format":"email",
            "pattern":"\\b[A-Za-z0-9._%+-]+@baeldung\\.com\\b"
        },
        "friends":{
            "maxItems":10,
            "type":"array",
            "items":{
                "$ref":"#"
            }
        },
        "fullName":{
            "type":[
                "string",
                "null"
            ]
        }
    },
    "required":[
        "createdAt",
        "email",
        "id",
        "name",
        "surname"
    ]
}

請注意，email 屬性由於在 Person 類中使用了 @Email 註解，因此具有 format 字段。同樣，friends 屬性的 maxItems 字段也已正確設置。

6. Maven 插件

Java JSON Schema Generator 提供一個 Maven 插件，用於從我們的構建流程中生成 Schema。 讓我們配置該插件：

<plugin>
    <groupId>com.github.victools</groupId>
    <artifactId>jsonschema-maven-plugin</artifactId>
    <version>4.31.1</version>
    <executions>
        <execution>
            <goals>
                <goal>generate</goal>
            </goals>
        </execution>
    </executions>
    <configuration>
        <packageNames>
            <packageName>com.baeldung.jsonschemageneration.plugin</packageName>
        </packageNames>
        <classNames>
            <className>com.baeldung.jsonschemageneration.plugin.Person</className>
        </classNames>
        <schemaVersion>DRAFT_2020_12</schemaVersion>
        <schemaFilePath>src/main/resources/schemas</schemaFilePath>
        <schemaFileName>{1}/{0}.json</schemaFileName>
        <failIfNoClassesMatch>true</failIfNoClassesMatch>
        <options>
            <preset>PLAIN_JSON</preset>
            <enabled>
                <option>DEFINITIONS_FOR_ALL_OBJECTS</option>
                <option>FORBIDDEN_ADDITIONAL_PROPERTIES_BY_DEFAULT</option>
            </enabled>
            <disabled>SCHEMA_VERSION_INDICATOR</disabled>
        </options>
        <modules>
            <module>
                <name>Jackson</name>
                <options>
                    <option>RESPECT_JSONPROPERTY_REQUIRED</option>
                </options>
            </module>
            <module>
                <name>JakartaValidation</name>
                <options>
                    <option>NOT_NULLABLE_FIELD_IS_REQUIRED</option>
                    <option>INCLUDE_PATTERN_EXPRESSIONS</option>
                </options>
            </module>
        </modules>
    </configuration>
</plugin>

我們將基於位於 com.baeldung.jsonschemageneration.plugin 包中的 Person 類生成一個模式。 我們可以仍然定義要使用的模塊，並向它們傳遞一些選項。 但是，該插件不允許為自定義模塊配置選項。

最後，生成的文件的命名模式由 {1}（即包名）和 {0}（即類名）組成。 它位於 src\main\resources\schemas\com\baeldung\jsonschemageneration\plugin\Person.json。 要生成它，讓我們運行 mvn compile。

生成的模式尊重插件配置中指定的所有條件。

7. 結論

在本文中，我們使用了 Java JSON Schema Generator 生成 Java 中的 JSON Schema。 在對 Schema 生成的基本概念的學習之後，我們瞭解瞭如何調整 Schema 配置。 隨後，我們探索了庫中的各種模塊以生成 JSON Schema。 最終，我們通過使用專門插件，將 JSON Schema 作為 Maven 的 generate 目標的一部分創建出來。