Jackson JSON 架构模块

该模块支持创建 JSON 架构 (v3)

请注意,由于 JSON 架构草案版本 3 和 4 是不兼容的,这个模块无法支持 v4。不过有另一个模块 mbknor-jackson-jsonSchema 支持 v4。

将来这个存储库可能会有两个不同的模块;一个用于 v3,另一个用于 v4。如果未来的修订同样不兼容,也可能会有更多版本。

状态

2.4 版本被认为是该模块的第一个稳定版本。

两个模块(与 Jackson 2.15 配合使用)

从即将到来的 Jackson 2.15 开始,这个存储库包含两个版本的模块:

旧的 JSON 架构模块com.fasterxml.jackson.module:jackson-module-jsonSchema(从 2.0 开始)
新的 JSON 架构模块com.fasterxml.jackson.module:jackson-module-jsonSchema-jakarta(2.15+)

这取决于系统是需要使用"旧"的javax/JAXB API(第一个模块)还是更新的"Jakarta"API。

未来计划(缺乏支持)

由于社区缺乏支持,这个模块计划不会超过 Jackson 2.x - 没有为它与未来的 Jackson 3.0 兼容而做任何工作。建议用户使用更新的 JSON 架构支持工具。

示例用法

(来自 TestGenerateJsonSchema)

只需添加依赖项 "com.fasterxml.jackson.module:jackson-module-jsonSchema:2.15.0" 或 "com.fasterxml.jackson.module:jackson-module-jsonSchema-jakarta:2.15.0"用于 jakarta 命名空间

对于 Gradle,您只需添加 mavenLocal() 到存储库中。 Maven 应该能够从本地存储库中透明地解析依赖关系。

ObjectMapper mapper = new ObjectMapper();
// 如有必要,配置 mapper,然后创建 schema 生成器
JsonSchemaGenerator schemaGen = new JsonSchemaGenerator(mapper);
JsonSchema schema = schemaGen.generateSchema(SimpleBean.class);

这将产生一个表示 JSON 架构的 Java POJO,可以使用 Jackson 轻松序列化,或用 Java 进行配置。定制生成应该只是找到您想要覆盖的特定生成阶段,并在 schema 工厂包装器的依赖注入周期中替换或扩展该特定对象。

添加属性处理

请参见 com.fasterxml.jackson.module.jsonSchema.customProperties.TitleSchemaFactoryWrapper 以了解编写自定义 schema 属性的示例。

必填字段

JSON 架构能够标记字段为必填。该模块通过 @JsonProperty(required = true) 字段注解支持此功能。

JsonSchema 超媒体支持

一般支持

当前实现对 IETF 发布的草案 v4 (http://json-schema.org/latest/json-schema-hypermedia.html) 是部分支持的。

当前 IETF 支持的两个方面:

pathStart - 定义实例的 URI 必须以此开头才能验证。
links - 与实例关联的链接描述对象。

您可以使用 com.fasterxml.jackson.module.jsonSchema.customProperties.HyperSchemaFactoryWrapper 启用超媒体支持。示例:

HyperSchemaFactoryWrapper personVisitor = new HyperSchemaFactoryWrapper();
ObjectMapper mapper = new ObjectMapper();
mapper.acceptJsonFormatVisitor(Person.class, personVisitor);
JsonSchema personSchema = personVisitor.finalSchema();

默认情况下,链接描述对象的所有默认值都被忽略在输出中(method = GET, enctype = application/json, mediaType = application/json),要启用默认值,请设置 setIgnoreDefaults(true)

描述 JSON 超架构

您可以使用注解 @JsonHyperSchema 和 @Link 来描述超链接

 public class Pet {
     public String genus;
 }

 @JsonHyperSchema(
     pathStart = "http://localhost:8080/persons/",
     links = {
         @Link(href = "{name}", rel = "self"),
         @Link(href = "{name}/pet", rel = "pet", targetSchema = Pet.class)
 })
 public class Person {
     public String name;
     public String hat;
 }

将生成以下值:

{
  "type" : "object",
  "pathStart" : "http://localhost:8080/persons/",
  "links" : [ {
    "href" : "http://localhost:8080/persons/{name}",
    "rel" : "self"
  }, {
    "href" : "http://localhost:8080/persons/{name}/pet",
    "rel" : "pet",
    "targetSchema" : {
      "type" : "object",
      "properties" : {
        "genus" : {
          "type" : "string"
        }
      }
    }
  } ],
  "properties" : {
    "name" : {
      "type" : "string"
    },
    "hat" : {
      "type" : "string"
    }
  }
}