From 040515b6a60ebf29b0f22de2d9c89d4182c6c596 Mon Sep 17 00:00:00 2001 From: Carsten Wickner <11309681+CarstenWickner@users.noreply.github.com> Date: Sat, 20 Feb 2021 22:23:48 +0100 Subject: [PATCH] Document usage of external references and avoid deprecated jackson API (#168) * chore(docs): add faq entry * chore: mention jackson version update in changelog * chore: replace deprecated jackson API usage as per version 2.12.0 --- CHANGELOG.md | 7 +++++ .../SchemaDefinitionNamingStrategyTest.java | 10 +++---- .../module/jackson/JacksonModule.java | 2 +- .../module/jackson/JacksonModuleTest.java | 4 +-- slate-docs/source/includes/_faq.md | 28 ++++++++++++++++++- 5 files changed, 41 insertions(+), 10 deletions(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index 553194bb..efa26023 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -5,10 +5,17 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/), and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html). ## [Unreleased] +### `jsonschema-generator` +#### Changed +- Increase of Jackson dependency version to 2.12.1 + ### `jsonschema-module-jackson` #### Added - New `JacksonOption.RESPECT_JSONPROPERTY_REQUIRED` to set a field as "required" based on `@JsonProperty` annotations +#### Changed +- Replace deprecated Jackson API usage, resulting in MINIMUM Jackson version 2.12.0 + ## [4.17.0] - 2020-12-24 ### `jsonschema-module-jakarta-validation` #### Added diff --git a/jsonschema-generator/src/test/java/com/github/victools/jsonschema/generator/naming/SchemaDefinitionNamingStrategyTest.java b/jsonschema-generator/src/test/java/com/github/victools/jsonschema/generator/naming/SchemaDefinitionNamingStrategyTest.java index 51250c86..1bfb32e0 100644 --- a/jsonschema-generator/src/test/java/com/github/victools/jsonschema/generator/naming/SchemaDefinitionNamingStrategyTest.java +++ b/jsonschema-generator/src/test/java/com/github/victools/jsonschema/generator/naming/SchemaDefinitionNamingStrategyTest.java @@ -16,13 +16,11 @@ package com.github.victools.jsonschema.generator.naming; -import com.github.victools.jsonschema.generator.naming.SchemaDefinitionNamingStrategy; import com.fasterxml.classmate.ResolvedType; -import com.fasterxml.jackson.databind.PropertyNamingStrategy; -import com.fasterxml.jackson.databind.PropertyNamingStrategy.PropertyNamingStrategyBase; +import com.fasterxml.jackson.databind.PropertyNamingStrategies; +import com.fasterxml.jackson.databind.PropertyNamingStrategies.NamingBase; import com.github.victools.jsonschema.generator.SchemaGenerationContext; import com.github.victools.jsonschema.generator.TypeContext; -import com.github.victools.jsonschema.generator.naming.DefaultSchemaDefinitionNamingStrategy; import com.github.victools.jsonschema.generator.impl.DefinitionKey; import com.github.victools.jsonschema.generator.impl.SchemaCleanUpUtils; import com.github.victools.jsonschema.generator.impl.TypeContextFactory; @@ -61,7 +59,7 @@ public void setUp() { } public Object[] parametersForTestExampleStrategy() { - PropertyNamingStrategyBase jacksonSnakeCase = new PropertyNamingStrategy.SnakeCaseStrategy(); + NamingBase jacksonSnakeCase = (NamingBase) PropertyNamingStrategies.SNAKE_CASE; SchemaDefinitionNamingStrategy snakeCase = new DefaultSchemaDefinitionNamingStrategy() { @Override public String getDefinitionNameForKey(DefinitionKey key, SchemaGenerationContext generationContext) { @@ -70,7 +68,7 @@ public String getDefinitionNameForKey(DefinitionKey key, SchemaGenerationContext .replaceAll(", _", ","); } }; - PropertyNamingStrategyBase jacksonDotCase = new PropertyNamingStrategy.LowerDotCaseStrategy(); + NamingBase jacksonDotCase = (NamingBase) PropertyNamingStrategies.LOWER_DOT_CASE; SchemaDefinitionNamingStrategy dotCase = new DefaultSchemaDefinitionNamingStrategy() { @Override public String getDefinitionNameForKey(DefinitionKey key, SchemaGenerationContext generationContext) { diff --git a/jsonschema-module-jackson/src/main/java/com/github/victools/jsonschema/module/jackson/JacksonModule.java b/jsonschema-module-jackson/src/main/java/com/github/victools/jsonschema/module/jackson/JacksonModule.java index 42f408f2..ef43c3d8 100644 --- a/jsonschema-module-jackson/src/main/java/com/github/victools/jsonschema/module/jackson/JacksonModule.java +++ b/jsonschema-module-jackson/src/main/java/com/github/victools/jsonschema/module/jackson/JacksonModule.java @@ -243,7 +243,7 @@ protected boolean shouldIgnoreField(FieldScope field) { BeanDescription beanDescription = this.getBeanDescriptionForClass(field.getDeclaringType()); // some kinds of field ignorals are only available via an annotation introspector Set ignoredProperties = this.objectMapper.getSerializationConfig().getAnnotationIntrospector() - .findPropertyIgnorals(beanDescription.getClassInfo()).getIgnored(); + .findPropertyIgnoralByName(null, beanDescription.getClassInfo()).getIgnored(); String fieldName = field.getName(); if (ignoredProperties.contains(fieldName)) { return true; diff --git a/jsonschema-module-jackson/src/test/java/com/github/victools/jsonschema/module/jackson/JacksonModuleTest.java b/jsonschema-module-jackson/src/test/java/com/github/victools/jsonschema/module/jackson/JacksonModuleTest.java index 35aec6b6..2bc467db 100644 --- a/jsonschema-module-jackson/src/test/java/com/github/victools/jsonschema/module/jackson/JacksonModuleTest.java +++ b/jsonschema-module-jackson/src/test/java/com/github/victools/jsonschema/module/jackson/JacksonModuleTest.java @@ -19,7 +19,7 @@ import com.fasterxml.jackson.annotation.JsonClassDescription; import com.fasterxml.jackson.annotation.JsonProperty; import com.fasterxml.jackson.annotation.JsonPropertyDescription; -import com.fasterxml.jackson.databind.PropertyNamingStrategy; +import com.fasterxml.jackson.databind.PropertyNamingStrategies; import com.fasterxml.jackson.databind.annotation.JsonNaming; import com.github.victools.jsonschema.generator.ConfigFunction; import com.github.victools.jsonschema.generator.FieldScope; @@ -265,7 +265,7 @@ public void testDescriptionForTypeResolver(String fieldName, String expectedDesc Assert.assertEquals(expectedDescription, description); } - @JsonNaming(PropertyNamingStrategy.KebabCaseStrategy.class) + @JsonNaming(PropertyNamingStrategies.KebabCaseStrategy.class) private static class TestClassForPropertyNameOverride { Integer unannotatedField; diff --git a/slate-docs/source/includes/_faq.md b/slate-docs/source/includes/_faq.md index 66237f08..e277171a 100644 --- a/slate-docs/source/includes/_faq.md +++ b/slate-docs/source/includes/_faq.md @@ -58,7 +58,7 @@ Enums are a special construct for which there are multiple options: 1. `Option.FLATTENED_ENUMS` (which is part of the `OptionPreset.PLAIN_JSON`) * This defines an enum as `{ "type": "string", "enum": ["VALUE1", "VALUE2"] }` with the `name()` method being called on each possible enum value. * If there is only one enum value, it will be set as `"const"` instead. - * Such an enum representation will always be in-lined and not moved into the `"definitions"`. + * Such an enum representation will always be in-lined and not moved into the `"definitions"`/`"$defs"`. 2. `Option.SIMPLIFIED_ENUMS`(which is part of the `OptionPreset.JAVA_OBJECT` and `OptionPreset.FULL_DOCUMENTATION`) * This treats enums like any other class but hiding some methods and listing the possible enum values as `"enum"`/`"const"` on the `name()` method. 3. Using neither of the two `Option`s above will let them be handled like any other class (unless there are further configurations taking care of enums). @@ -134,3 +134,29 @@ The exact details depend on how the `default` value can be determined. 1. If the `default` value is explicitly stated via some kind of annotation, it might be as simple as "Example 1" on the right. 2. If the `default` value is only set in code, and you cannot or don't want to maintain that piece of information twice this can get a bit more advanced. Here assuming your own classes all have a default no-args constructor and conventional getters as in "Example 2" on the right. + +## How to reference a separate schema/file? + +```java +configBuilder.forTypesInGeneral() + .withCustomDefinitionProvider((javaType, context) -> { + if (javaType.getErasedType() != MyExternalType.class) { + // other types should be treated normally + return null; + } + // define your custom reference value + String refValue = "./" + javaType.getErasedType().getSimpleName(); + // produce the sub-schema that only contains your custom reference + ObjectNode customNode = context.getGeneratorConfig().createObjectNode() + .put(context.getKeyword(SchemaKeyword.TAG_REF), refValue); + return new CustomDefinition(customNode, + // avoid the creation of a reference to your custom reference schema + CustomDefinition.DefinitionType.INLINE, + // still allow for collected schema attributes to be added + CustomDefinition.AttributeInclusion.YES); + }); +``` + +By using `withCustomDefinitionProvider()` – one of the [advanced configurations](#generator-advanced-configurations) – you can fully control the contents of a type's sub-schema. +Simply create a node that only contains your custom/external reference instead of the actual schema. +It is recommended to mark the custom definition as "to be inlined", in order to avoid an extra entry in the `"definitions"`/`"$defs"`.