From 40d639e8afc2d992af177df5a88378bc9a9261ec Mon Sep 17 00:00:00 2001 From: Christoph Kappestein Date: Fri, 29 Nov 2024 23:00:35 +0100 Subject: [PATCH] use json class and property description annotation --- src/Generator/Java.php | 18 ++++++++++-------- .../resource/java/complex/AnyPropertyType.java | 4 +--- .../java/complex/ArrayDefinitionType.java | 4 +--- .../java/complex/ArrayPropertyType.java | 4 +--- .../java/complex/BooleanPropertyType.java | 4 +--- .../java/complex/CollectionDefinitionType.java | 4 +--- .../java/complex/CollectionPropertyType.java | 4 +--- .../resource/java/complex/DefinitionType.java | 4 +--- .../java/complex/GenericPropertyType.java | 5 ++--- .../java/complex/IntegerPropertyType.java | 4 +--- .../java/complex/MapDefinitionType.java | 4 +--- .../resource/java/complex/MapPropertyType.java | 4 +--- .../java/complex/NumberPropertyType.java | 4 +--- .../resource/java/complex/PropertyType.java | 4 +--- .../java/complex/ReferencePropertyType.java | 6 +++--- .../java/complex/ScalarPropertyType.java | 4 +--- .../java/complex/StringPropertyType.java | 5 ++--- .../java/complex/StructDefinitionType.java | 9 ++++++--- .../resource/java/complex/TypeSchema.java | 6 +++--- .../resource/java/default/Author.java | 6 +++--- .../resource/java/default/Location.java | 4 +--- .../Generator/resource/java/default/News.java | 5 ++--- 22 files changed, 45 insertions(+), 71 deletions(-) diff --git a/src/Generator/Java.php b/src/Generator/Java.php index 1f53644..3947423 100644 --- a/src/Generator/Java.php +++ b/src/Generator/Java.php @@ -69,6 +69,11 @@ protected function writeStruct(Code\Name $name, array $properties, ?string $exte $code.= '})' . "\n"; } + $comment = $origin->getDescription(); + if (!empty($comment)) { + $code.= '@JsonClassDescription("' . $comment . '")' . "\n"; + } + $code.= 'public ' . ($origin->getBase() === true ? 'abstract ' : '') . 'class ' . $name->getClass(); if (!empty($generics)) { @@ -86,6 +91,11 @@ protected function writeStruct(Code\Name $name, array $properties, ?string $exte foreach ($properties as $property) { /** @var Code\Property $property */ + $comment = $property->getComment(); + if (!empty($comment)) { + $code.= $this->indent . '@JsonPropertyDescription("' . $comment . '")' . "\n"; + } + $code.= $this->indent . 'private ' . $property->getType() . ' ' . $property->getName()->getProperty() . ';' . "\n"; } @@ -139,14 +149,6 @@ protected function writeHeader(DefinitionTypeAbstract $origin, Code\Name $classN $code.= "\n"; } - $comment = $origin->getDescription(); - if (!empty($comment)) { - $code.= "\n"; - $code.= '/**' . "\n"; - $code.= ' * ' . $comment . "\n"; - $code.= ' */'; - } - return $code; } diff --git a/tests/Generator/resource/java/complex/AnyPropertyType.java b/tests/Generator/resource/java/complex/AnyPropertyType.java index cd24967..4b04437 100644 --- a/tests/Generator/resource/java/complex/AnyPropertyType.java +++ b/tests/Generator/resource/java/complex/AnyPropertyType.java @@ -2,9 +2,7 @@ import com.fasterxml.jackson.annotation.*; -/** - * Represents an any value which allows any kind of value - */ +@JsonClassDescription("Represents an any value which allows any kind of value") public class AnyPropertyType extends PropertyType { } diff --git a/tests/Generator/resource/java/complex/ArrayDefinitionType.java b/tests/Generator/resource/java/complex/ArrayDefinitionType.java index 567f8c1..15cdd02 100644 --- a/tests/Generator/resource/java/complex/ArrayDefinitionType.java +++ b/tests/Generator/resource/java/complex/ArrayDefinitionType.java @@ -2,9 +2,7 @@ import com.fasterxml.jackson.annotation.*; -/** - * Represents an array which contains a dynamic list of values of the same type - */ +@JsonClassDescription("Represents an array which contains a dynamic list of values of the same type") public class ArrayDefinitionType extends CollectionDefinitionType { } diff --git a/tests/Generator/resource/java/complex/ArrayPropertyType.java b/tests/Generator/resource/java/complex/ArrayPropertyType.java index f1f66f9..e93aff2 100644 --- a/tests/Generator/resource/java/complex/ArrayPropertyType.java +++ b/tests/Generator/resource/java/complex/ArrayPropertyType.java @@ -2,9 +2,7 @@ import com.fasterxml.jackson.annotation.*; -/** - * Represents an array which contains a dynamic list of values of the same type - */ +@JsonClassDescription("Represents an array which contains a dynamic list of values of the same type") public class ArrayPropertyType extends CollectionPropertyType { } diff --git a/tests/Generator/resource/java/complex/BooleanPropertyType.java b/tests/Generator/resource/java/complex/BooleanPropertyType.java index 0f52926..2651487 100644 --- a/tests/Generator/resource/java/complex/BooleanPropertyType.java +++ b/tests/Generator/resource/java/complex/BooleanPropertyType.java @@ -2,9 +2,7 @@ import com.fasterxml.jackson.annotation.*; -/** - * Represents a boolean value - */ +@JsonClassDescription("Represents a boolean value") public class BooleanPropertyType extends ScalarPropertyType { } diff --git a/tests/Generator/resource/java/complex/CollectionDefinitionType.java b/tests/Generator/resource/java/complex/CollectionDefinitionType.java index 6c0f651..e760e7c 100644 --- a/tests/Generator/resource/java/complex/CollectionDefinitionType.java +++ b/tests/Generator/resource/java/complex/CollectionDefinitionType.java @@ -2,14 +2,12 @@ import com.fasterxml.jackson.annotation.*; -/** - * Base collection type - */ @JsonTypeInfo(use = JsonTypeInfo.Id.NAME, property = "type") @JsonSubTypes({ @JsonSubTypes.Type(value = ArrayDefinitionType.class, name = "array"), @JsonSubTypes.Type(value = MapDefinitionType.class, name = "map"), }) +@JsonClassDescription("Base collection type") public abstract class CollectionDefinitionType extends DefinitionType { private PropertyType schema; private String type; diff --git a/tests/Generator/resource/java/complex/CollectionPropertyType.java b/tests/Generator/resource/java/complex/CollectionPropertyType.java index 9557563..fab2f81 100644 --- a/tests/Generator/resource/java/complex/CollectionPropertyType.java +++ b/tests/Generator/resource/java/complex/CollectionPropertyType.java @@ -2,14 +2,12 @@ import com.fasterxml.jackson.annotation.*; -/** - * Base collection property type - */ @JsonTypeInfo(use = JsonTypeInfo.Id.NAME, property = "type") @JsonSubTypes({ @JsonSubTypes.Type(value = ArrayPropertyType.class, name = "array"), @JsonSubTypes.Type(value = MapPropertyType.class, name = "map"), }) +@JsonClassDescription("Base collection property type") public abstract class CollectionPropertyType extends PropertyType { private PropertyType schema; private String type; diff --git a/tests/Generator/resource/java/complex/DefinitionType.java b/tests/Generator/resource/java/complex/DefinitionType.java index b9a2767..7b59c88 100644 --- a/tests/Generator/resource/java/complex/DefinitionType.java +++ b/tests/Generator/resource/java/complex/DefinitionType.java @@ -2,15 +2,13 @@ import com.fasterxml.jackson.annotation.*; -/** - * Base definition type - */ @JsonTypeInfo(use = JsonTypeInfo.Id.NAME, property = "type") @JsonSubTypes({ @JsonSubTypes.Type(value = ArrayDefinitionType.class, name = "array"), @JsonSubTypes.Type(value = MapDefinitionType.class, name = "map"), @JsonSubTypes.Type(value = StructDefinitionType.class, name = "struct"), }) +@JsonClassDescription("Base definition type") public abstract class DefinitionType { private Boolean deprecated; private String description; diff --git a/tests/Generator/resource/java/complex/GenericPropertyType.java b/tests/Generator/resource/java/complex/GenericPropertyType.java index 2140efe..02c1e88 100644 --- a/tests/Generator/resource/java/complex/GenericPropertyType.java +++ b/tests/Generator/resource/java/complex/GenericPropertyType.java @@ -2,10 +2,9 @@ import com.fasterxml.jackson.annotation.*; -/** - * Represents a generic value which can be replaced with a dynamic type - */ +@JsonClassDescription("Represents a generic value which can be replaced with a dynamic type") public class GenericPropertyType extends PropertyType { + @JsonPropertyDescription("The name of the generic, it is recommended to use common generic names like T or TValue. These generics can then be replaced on usage with a concrete type through the template property at a reference.") private String name; @JsonSetter("name") diff --git a/tests/Generator/resource/java/complex/IntegerPropertyType.java b/tests/Generator/resource/java/complex/IntegerPropertyType.java index 1ecfe56..e58c50a 100644 --- a/tests/Generator/resource/java/complex/IntegerPropertyType.java +++ b/tests/Generator/resource/java/complex/IntegerPropertyType.java @@ -2,9 +2,7 @@ import com.fasterxml.jackson.annotation.*; -/** - * Represents an integer value - */ +@JsonClassDescription("Represents an integer value") public class IntegerPropertyType extends ScalarPropertyType { } diff --git a/tests/Generator/resource/java/complex/MapDefinitionType.java b/tests/Generator/resource/java/complex/MapDefinitionType.java index 4a7a5b9..6112039 100644 --- a/tests/Generator/resource/java/complex/MapDefinitionType.java +++ b/tests/Generator/resource/java/complex/MapDefinitionType.java @@ -2,9 +2,7 @@ import com.fasterxml.jackson.annotation.*; -/** - * Represents a map which contains a dynamic set of key value entries of the same type - */ +@JsonClassDescription("Represents a map which contains a dynamic set of key value entries of the same type") public class MapDefinitionType extends CollectionDefinitionType { } diff --git a/tests/Generator/resource/java/complex/MapPropertyType.java b/tests/Generator/resource/java/complex/MapPropertyType.java index 186d6ae..dbf8fb6 100644 --- a/tests/Generator/resource/java/complex/MapPropertyType.java +++ b/tests/Generator/resource/java/complex/MapPropertyType.java @@ -2,9 +2,7 @@ import com.fasterxml.jackson.annotation.*; -/** - * Represents a map which contains a dynamic set of key value entries of the same type - */ +@JsonClassDescription("Represents a map which contains a dynamic set of key value entries of the same type") public class MapPropertyType extends CollectionPropertyType { } diff --git a/tests/Generator/resource/java/complex/NumberPropertyType.java b/tests/Generator/resource/java/complex/NumberPropertyType.java index c8a040a..6da6708 100644 --- a/tests/Generator/resource/java/complex/NumberPropertyType.java +++ b/tests/Generator/resource/java/complex/NumberPropertyType.java @@ -2,9 +2,7 @@ import com.fasterxml.jackson.annotation.*; -/** - * Represents a float value - */ +@JsonClassDescription("Represents a float value") public class NumberPropertyType extends ScalarPropertyType { } diff --git a/tests/Generator/resource/java/complex/PropertyType.java b/tests/Generator/resource/java/complex/PropertyType.java index 4605c39..8330a09 100644 --- a/tests/Generator/resource/java/complex/PropertyType.java +++ b/tests/Generator/resource/java/complex/PropertyType.java @@ -2,9 +2,6 @@ import com.fasterxml.jackson.annotation.*; -/** - * Base property type - */ @JsonTypeInfo(use = JsonTypeInfo.Id.NAME, property = "type") @JsonSubTypes({ @JsonSubTypes.Type(value = AnyPropertyType.class, name = "any"), @@ -17,6 +14,7 @@ @JsonSubTypes.Type(value = ReferencePropertyType.class, name = "reference"), @JsonSubTypes.Type(value = StringPropertyType.class, name = "string"), }) +@JsonClassDescription("Base property type") public abstract class PropertyType { private Boolean deprecated; private String description; diff --git a/tests/Generator/resource/java/complex/ReferencePropertyType.java b/tests/Generator/resource/java/complex/ReferencePropertyType.java index 04310f2..4cf7bf6 100644 --- a/tests/Generator/resource/java/complex/ReferencePropertyType.java +++ b/tests/Generator/resource/java/complex/ReferencePropertyType.java @@ -2,11 +2,11 @@ import com.fasterxml.jackson.annotation.*; -/** - * Represents a reference to a definition type - */ +@JsonClassDescription("Represents a reference to a definition type") public class ReferencePropertyType extends PropertyType { + @JsonPropertyDescription("The target type, this must be a key which is available under the definitions keyword.") private String target; + @JsonPropertyDescription("A map where the key is the name of the generic and the value must point to a key under the definitions keyword. This can be used in case the target points to a type which contains generics, then it is possible to replace those generics with a concrete type.") private java.util.Map template; @JsonSetter("target") diff --git a/tests/Generator/resource/java/complex/ScalarPropertyType.java b/tests/Generator/resource/java/complex/ScalarPropertyType.java index a110778..045bb2d 100644 --- a/tests/Generator/resource/java/complex/ScalarPropertyType.java +++ b/tests/Generator/resource/java/complex/ScalarPropertyType.java @@ -2,9 +2,6 @@ import com.fasterxml.jackson.annotation.*; -/** - * Base scalar property type - */ @JsonTypeInfo(use = JsonTypeInfo.Id.NAME, property = "type") @JsonSubTypes({ @JsonSubTypes.Type(value = BooleanPropertyType.class, name = "boolean"), @@ -12,6 +9,7 @@ @JsonSubTypes.Type(value = NumberPropertyType.class, name = "number"), @JsonSubTypes.Type(value = StringPropertyType.class, name = "string"), }) +@JsonClassDescription("Base scalar property type") public abstract class ScalarPropertyType extends PropertyType { private String type; diff --git a/tests/Generator/resource/java/complex/StringPropertyType.java b/tests/Generator/resource/java/complex/StringPropertyType.java index 1472702..459c7c2 100644 --- a/tests/Generator/resource/java/complex/StringPropertyType.java +++ b/tests/Generator/resource/java/complex/StringPropertyType.java @@ -2,10 +2,9 @@ import com.fasterxml.jackson.annotation.*; -/** - * Represents a string value - */ +@JsonClassDescription("Represents a string value") public class StringPropertyType extends ScalarPropertyType { + @JsonPropertyDescription("Optional describes the format of the string. Supported are the following types: date, date-time and time. A code generator may use a fitting data type to represent such a format, if not supported it should fall back to a string.") private String format; @JsonSetter("format") diff --git a/tests/Generator/resource/java/complex/StructDefinitionType.java b/tests/Generator/resource/java/complex/StructDefinitionType.java index a3cec94..8e4498e 100644 --- a/tests/Generator/resource/java/complex/StructDefinitionType.java +++ b/tests/Generator/resource/java/complex/StructDefinitionType.java @@ -2,14 +2,17 @@ import com.fasterxml.jackson.annotation.*; -/** - * A struct represents a class/structure with a fix set of defined properties. - */ +@JsonClassDescription("A struct represents a class/structure with a fix set of defined properties.") public class StructDefinitionType extends DefinitionType { + @JsonPropertyDescription("Indicates whether this is a base structure, default is false. If true the structure is used a base type, this means it is not possible to create an instance from this structure.") private Boolean base; + @JsonPropertyDescription("Optional the property name of a discriminator property. This should be only used in case this is also a base structure.") private String discriminator; + @JsonPropertyDescription("In case a discriminator is configured it is required to configure a mapping. The mapping is a map where the key is the type name and the value the actual discriminator type value.") private java.util.Map mapping; + @JsonPropertyDescription("Defines a parent type for this structure. Some programming languages like Go do not support the concept of an extends, in this case the code generator simply copies all properties into this structure.") private ReferencePropertyType parent; + @JsonPropertyDescription("Contains a map of available properties for this struct.") private java.util.Map properties; @JsonSetter("base") diff --git a/tests/Generator/resource/java/complex/TypeSchema.java b/tests/Generator/resource/java/complex/TypeSchema.java index f434cce..5d61298 100644 --- a/tests/Generator/resource/java/complex/TypeSchema.java +++ b/tests/Generator/resource/java/complex/TypeSchema.java @@ -2,12 +2,12 @@ import com.fasterxml.jackson.annotation.*; -/** - * TypeSchema specification - */ +@JsonClassDescription("TypeSchema specification") public class TypeSchema { private java.util.Map definitions; + @JsonPropertyDescription("Through the import keyword it is possible to import other TypeSchema documents. It contains a map where the key is the namespace and the value points to a remote document. The value is a URL and a code generator should support at least the following schemes: file, http, https.") private java.util.Map _import; + @JsonPropertyDescription("Specifies the root type of your specification.") private String root; @JsonSetter("definitions") diff --git a/tests/Generator/resource/java/default/Author.java b/tests/Generator/resource/java/default/Author.java index 8fdc0ff..f9ee391 100644 --- a/tests/Generator/resource/java/default/Author.java +++ b/tests/Generator/resource/java/default/Author.java @@ -1,13 +1,13 @@ import com.fasterxml.jackson.annotation.*; -/** - * An simple author element with some description - */ +@JsonClassDescription("An simple author element with some description") public class Author { private String title; + @JsonPropertyDescription("We will send no spam to this address") private String email; private java.util.List categories; + @JsonPropertyDescription("Array of locations") private java.util.List locations; private Location origin; diff --git a/tests/Generator/resource/java/default/Location.java b/tests/Generator/resource/java/default/Location.java index 4c3fbfc..55ba7cc 100644 --- a/tests/Generator/resource/java/default/Location.java +++ b/tests/Generator/resource/java/default/Location.java @@ -1,9 +1,7 @@ import com.fasterxml.jackson.annotation.*; -/** - * Location of the person - */ +@JsonClassDescription("Location of the person") public class Location { private Double lat; private Double _long; diff --git a/tests/Generator/resource/java/default/News.java b/tests/Generator/resource/java/default/News.java index 2c08e52..58cfe35 100644 --- a/tests/Generator/resource/java/default/News.java +++ b/tests/Generator/resource/java/default/News.java @@ -1,9 +1,7 @@ import com.fasterxml.jackson.annotation.*; -/** - * An general news entry - */ +@JsonClassDescription("An general news entry") public class News { private Meta config; private java.util.Map inlineConfig; @@ -18,6 +16,7 @@ public class News { private java.time.LocalDateTime readDate; private Double price; private Integer rating; + @JsonPropertyDescription("Contains the main content of the news entry") private String content; private String question; private String version;