create object schema & properties javadoc

hauner · hauner · commit 5ddc052dead6 · 2021-03-13T20:12:35.000+01:00
diff --git a/openapi-processor-core/src/main/kotlin/io/openapiprocessor/core/converter/DataTypeConverter.kt b/openapi-processor-core/src/main/kotlin/io/openapiprocessor/core/converter/DataTypeConverter.kt
@@ -204,9 +204,7 @@ class DataTypeConverter(
             properties = properties,
             constraints = constraints,
             deprecated = schemaInfo.getDeprecated(),
-            documentation = Documentation(
-                description = schemaInfo.description
-            )
+            documentation = Documentation(description = schemaInfo.description)
         )
 
         dataTypes.add (objectType)
@@ -246,22 +244,29 @@ class DataTypeConverter(
         return when(typeFormat) {
             "integer",
             "integer:int32" ->
-                IntegerDataType(constraints, schemaInfo.getDeprecated())
+                IntegerDataType(constraints, schemaInfo.getDeprecated(),
+                    Documentation(description = schemaInfo.description))
             "integer:int64" ->
-                LongDataType(constraints, schemaInfo.getDeprecated())
+                LongDataType(constraints, schemaInfo.getDeprecated(),
+                    Documentation(description = schemaInfo.description))
             "number",
             "number:float" ->
-                FloatDataType(constraints, schemaInfo.getDeprecated())
+                FloatDataType(constraints, schemaInfo.getDeprecated(),
+                    Documentation(description = schemaInfo.description))
             "number:double" ->
-                DoubleDataType(constraints, schemaInfo.getDeprecated())
+                DoubleDataType(constraints, schemaInfo.getDeprecated(),
+                    Documentation(description = schemaInfo.description))
             "boolean" ->
-                BooleanDataType(constraints, schemaInfo.getDeprecated())
+                BooleanDataType(constraints, schemaInfo.getDeprecated(),
+                    Documentation(description = schemaInfo.description))
             "string" ->
                 createStringDataType(schemaInfo, constraints, dataTypes)
             "string:date" ->
-                LocalDateDataType(constraints, schemaInfo.getDeprecated())
+                LocalDateDataType(constraints, schemaInfo.getDeprecated(),
+                    Documentation(description = schemaInfo.description))
             "string:date-time" ->
-                OffsetDateTimeDataType (constraints, schemaInfo.getDeprecated())
+                OffsetDateTimeDataType (constraints, schemaInfo.getDeprecated(),
+                    Documentation(description = schemaInfo.description))
             else ->
                 throw UnknownDataTypeException(schemaInfo.getName(), schemaInfo.getType(),
                     schemaInfo.getFormat())
@@ -294,9 +299,12 @@ class DataTypeConverter(
             "date-time")
     }
 
-    private fun createStringDataType(schemaInfo: SchemaInfo, constraints: DataTypeConstraints, dataTypes: DataTypes): DataType {
+    private fun createStringDataType(schemaInfo: SchemaInfo, constraints: DataTypeConstraints,
+        dataTypes: DataTypes): DataType {
+
         if (!schemaInfo.isEnum()) {
-            return StringDataType(constraints, schemaInfo.getDeprecated())
+            return StringDataType(constraints, schemaInfo.getDeprecated(),
+                Documentation(description = schemaInfo.description))
         }
 
         // in case of an inline definition the name may be lowercase, make sure the enum
diff --git a/openapi-processor-core/src/main/kotlin/io/openapiprocessor/core/model/datatypes/BooleanDataType.kt b/openapi-processor-core/src/main/kotlin/io/openapiprocessor/core/model/datatypes/BooleanDataType.kt
@@ -16,6 +16,8 @@
 
 package io.openapiprocessor.core.model.datatypes
 
+import io.openapiprocessor.core.model.Documentation
+
 /**
  * OpenAPI type 'boolean' maps to java Boolean.
  *
@@ -24,9 +26,10 @@ package io.openapiprocessor.core.model.datatypes
 class BooleanDataType(
 
    constraints: DataTypeConstraints? = null,
-   deprecated: Boolean = false
+   deprecated: Boolean = false,
+   documentation: Documentation? = null
 
-): DataTypeBase(constraints, deprecated) {
+): DataTypeBase(constraints, deprecated, documentation) {
 
     override fun getName(): String {
         return "Boolean"
diff --git a/openapi-processor-core/src/main/kotlin/io/openapiprocessor/core/model/datatypes/DoubleDataType.kt b/openapi-processor-core/src/main/kotlin/io/openapiprocessor/core/model/datatypes/DoubleDataType.kt
@@ -16,6 +16,8 @@
 
 package io.openapiprocessor.core.model.datatypes
 
+import io.openapiprocessor.core.model.Documentation
+
 /**
  * OpenAPI type 'number' with format 'double' maps to java Double.
  *
@@ -24,9 +26,10 @@ package io.openapiprocessor.core.model.datatypes
 class DoubleDataType(
 
     constraints: DataTypeConstraints? = null,
-    deprecated: Boolean = false
+    deprecated: Boolean = false,
+    documentation: Documentation? = null
 
-): DataTypeBase(constraints, deprecated) {
+): DataTypeBase(constraints, deprecated, documentation) {
 
     override fun getName(): String {
         return "Double"
diff --git a/openapi-processor-core/src/main/kotlin/io/openapiprocessor/core/model/datatypes/FloatDataType.kt b/openapi-processor-core/src/main/kotlin/io/openapiprocessor/core/model/datatypes/FloatDataType.kt
@@ -16,6 +16,8 @@
 
 package io.openapiprocessor.core.model.datatypes
 
+import io.openapiprocessor.core.model.Documentation
+
 /**
  * OpenAPI type 'number' with format 'float' maps to java Float.
  *
@@ -24,9 +26,10 @@ package io.openapiprocessor.core.model.datatypes
 class FloatDataType(
 
     constraints: DataTypeConstraints? = null,
-    deprecated: Boolean = false
+    deprecated: Boolean = false,
+    documentation: Documentation? = null
 
-): DataTypeBase(constraints, deprecated) {
+): DataTypeBase(constraints, deprecated, documentation) {
 
     override fun getName(): String {
         return "Float"
diff --git a/openapi-processor-core/src/main/kotlin/io/openapiprocessor/core/model/datatypes/IntegerDataType.kt b/openapi-processor-core/src/main/kotlin/io/openapiprocessor/core/model/datatypes/IntegerDataType.kt
@@ -16,6 +16,8 @@
 
 package io.openapiprocessor.core.model.datatypes
 
+import io.openapiprocessor.core.model.Documentation
+
 /**
  * OpenAPI type 'integer' with format 'int32' maps to java Integer.
  *
@@ -24,9 +26,10 @@ package io.openapiprocessor.core.model.datatypes
 class IntegerDataType(
 
     constraints: DataTypeConstraints? = null,
-    deprecated: Boolean = false
+    deprecated: Boolean = false,
+    documentation: Documentation? = null
 
-): DataTypeBase(constraints, deprecated) {
+): DataTypeBase(constraints, deprecated, documentation) {
 
     override fun getName(): String {
         return "Integer"
diff --git a/openapi-processor-core/src/main/kotlin/io/openapiprocessor/core/model/datatypes/LocalDateDataType.kt b/openapi-processor-core/src/main/kotlin/io/openapiprocessor/core/model/datatypes/LocalDateDataType.kt
@@ -16,6 +16,8 @@
 
 package io.openapiprocessor.core.model.datatypes
 
+import io.openapiprocessor.core.model.Documentation
+
 /**
  * OpenAPI type 'string' with format 'date' maps to java LocalDate.
  *
@@ -24,9 +26,10 @@ package io.openapiprocessor.core.model.datatypes
 class LocalDateDataType(
 
     constraints: DataTypeConstraints? = null,
-    deprecated: Boolean = false
+    deprecated: Boolean = false,
+    documentation: Documentation? = null
 
-): DataTypeBase(constraints, deprecated) {
+): DataTypeBase(constraints, deprecated, documentation) {
 
     override fun getName(): String {
         return "LocalDate"
@@ -35,5 +38,5 @@ class LocalDateDataType(
     override fun getPackageName(): String {
         return "java.time"
     }
-    
+
 }
diff --git a/openapi-processor-core/src/main/kotlin/io/openapiprocessor/core/model/datatypes/LongDataType.kt b/openapi-processor-core/src/main/kotlin/io/openapiprocessor/core/model/datatypes/LongDataType.kt
@@ -16,6 +16,8 @@
 
 package io.openapiprocessor.core.model.datatypes
 
+import io.openapiprocessor.core.model.Documentation
+
 /**
  * OpenAPI type 'integer' with format 'int64' maps to java Long.
  *
@@ -24,9 +26,10 @@ package io.openapiprocessor.core.model.datatypes
 class LongDataType(
 
     constraints: DataTypeConstraints? = null,
-    deprecated: Boolean = false
+    deprecated: Boolean = false,
+    documentation: Documentation? = null
 
-): DataTypeBase(constraints, deprecated) {
+): DataTypeBase(constraints, deprecated, documentation) {
 
     override fun getName(): String {
         return "Long"
diff --git a/openapi-processor-core/src/main/kotlin/io/openapiprocessor/core/model/datatypes/OffsetDateTimeDataType.kt b/openapi-processor-core/src/main/kotlin/io/openapiprocessor/core/model/datatypes/OffsetDateTimeDataType.kt
@@ -16,6 +16,8 @@
 
 package io.openapiprocessor.core.model.datatypes
 
+import io.openapiprocessor.core.model.Documentation
+
 /**
  * OpenAPI type 'string' with format 'date-time' maps to java OffsetDateTime.
  *
@@ -24,7 +26,8 @@ package io.openapiprocessor.core.model.datatypes
 class OffsetDateTimeDataType(
 
     constraints: DataTypeConstraints? = null,
-    deprecated: Boolean = false
+    deprecated: Boolean = false,
+    documentation: Documentation? = null
 
 ): DataTypeBase(constraints, deprecated) {
 
diff --git a/openapi-processor-core/src/main/kotlin/io/openapiprocessor/core/model/datatypes/StringDataType.kt b/openapi-processor-core/src/main/kotlin/io/openapiprocessor/core/model/datatypes/StringDataType.kt
@@ -16,6 +16,8 @@
 
 package io.openapiprocessor.core.model.datatypes
 
+import io.openapiprocessor.core.model.Documentation
+
 /**
  * OpenAPI type 'string' maps to java String.
  *
@@ -24,9 +26,10 @@ package io.openapiprocessor.core.model.datatypes
 class StringDataType(
 
     constraints: DataTypeConstraints? = null,
-    deprecated: Boolean = false
+    deprecated: Boolean = false,
+    documentation: Documentation? = null
 
-): DataTypeBase(constraints, deprecated) {
+): DataTypeBase(constraints, deprecated, documentation) {
 
     override fun getName(): String {
         return "String"
diff --git a/openapi-processor-core/src/main/kotlin/io/openapiprocessor/core/writer/java/DataTypeWriter.kt b/openapi-processor-core/src/main/kotlin/io/openapiprocessor/core/writer/java/DataTypeWriter.kt
@@ -65,6 +65,11 @@ class DataTypeWriter(
         propDataType: DataType, required: Boolean): String {
 
         var result = ""
+
+        if (apiOptions.javadoc) {
+            result += javadocWriter.convert(propDataType)
+        }
+
         if (propDataType.isDeprecated()) {
             result += "    @Deprecated\n"
         }
diff --git a/openapi-processor-core/src/main/kotlin/io/openapiprocessor/core/writer/java/JavaDocWriter.kt b/openapi-processor-core/src/main/kotlin/io/openapiprocessor/core/writer/java/JavaDocWriter.kt
@@ -7,6 +7,7 @@ package io.openapiprocessor.core.writer.java
 
 import io.openapiprocessor.core.model.Endpoint
 import io.openapiprocessor.core.model.EndpointResponse
+import io.openapiprocessor.core.model.datatypes.DataType
 import io.openapiprocessor.core.model.datatypes.ModelDataType
 import org.commonmark.node.Document
 import org.commonmark.node.Node
@@ -88,6 +89,16 @@ open class JavaDocWriter {
         return wrap(comment)
     }
 
+    fun convert(dataType: DataType): String {
+        var comment = ""
+
+        if (dataType.documentation?.description != null) {
+            comment += convert(dataType.documentation!!.description) + "\n"
+        }
+
+        return indent(wrap(comment))
+    }
+
     private fun wrap(comment: String): String {
         val temp = comment
             .dropLastWhile { it == '\n' }
diff --git a/openapi-processor-core/src/test/groovy/com/github/hauner/openapi/core/learn/PropertyNotationSpec.groovy b/openapi-processor-core/src/test/groovy/com/github/hauner/openapi/core/learn/PropertyNotationSpec.groovy
@@ -32,8 +32,10 @@ class PropertyNotationSpec extends Specification {
         // CompositeDataType must not implement a getProperty() method. It overrides groovy's
         // getProperty() and that breaks the groovy property notation.
 
-        def object = new ObjectDataType ('Type', 'pkg', [:], null, false)
-        DataType typed = new ObjectDataType ('Typed', 'pkg', [:],null, false)
+        def object = new ObjectDataType (
+            'Type', 'pkg', [:], null, false, null)
+        DataType typed = new ObjectDataType (
+            'Typed', 'pkg', [:],null, false, null)
 
         expect:
         object.name != null
diff --git a/openapi-processor-core/src/test/groovy/com/github/hauner/openapi/core/model/EndpointContentTypesSpec.groovy b/openapi-processor-core/src/test/groovy/com/github/hauner/openapi/core/model/EndpointContentTypesSpec.groovy
@@ -48,7 +48,7 @@ class EndpointContentTypesSpec extends Specification {
                     new ObjectDataType ('Foo', '', [
                         foo: new StringDataType (),
                         bar: new StringDataType ()
-                    ], null, false))
+                    ], null, false, null))
             }
             e.responses { r ->
                 r.status ('204') {it.empty () }
diff --git a/openapi-processor-core/src/test/groovy/com/github/hauner/openapi/core/writer/java/BeanValidationFactorySpec.groovy b/openapi-processor-core/src/test/groovy/com/github/hauner/openapi/core/writer/java/BeanValidationFactorySpec.groovy
@@ -44,7 +44,8 @@ class BeanValidationFactorySpec extends Specification {
 
     @Unroll
     void "applies @Valid to Object" () {
-        def dataType = new ObjectDataType('Foo', '', [:], null, false)
+        def dataType = new ObjectDataType(
+            'Foo', '', [:], null, false, null)
 
         when:
         def imports = validation.collectImports (dataType, false)
@@ -82,7 +83,7 @@ class BeanValidationFactorySpec extends Specification {
             maxLength: maxLength
         )
 
-        def dataType = new StringDataType(constraints, false)
+        def dataType = new StringDataType(constraints, false, null)
 
         when:
         def imports = validation.collectImports (dataType, false)
@@ -299,7 +300,7 @@ class BeanValidationFactorySpec extends Specification {
         constraints.maximum = maximum
         constraints.exclusiveMaximum = exclusiveMaximum
 
-        DataType dataType = new DoubleDataType (constraints, false)
+        DataType dataType = new DoubleDataType (constraints, false, null)
 
         when:
         def imports = validation.collectImports (dataType, false)
@@ -322,19 +323,19 @@ class BeanValidationFactorySpec extends Specification {
     private DataType createDataType (Class clazz, DataTypeConstraints constraints) {
         switch (clazz) {
             case IntegerDataType:
-                return new IntegerDataType(constraints, false)
+                return new IntegerDataType(constraints, false, null)
 
             case LongDataType:
-                return new LongDataType(constraints, false)
+                return new LongDataType(constraints, false, null)
 
             case FloatDataType:
-                return new FloatDataType(constraints, false)
+                return new FloatDataType(constraints, false, null)
 
             case DoubleDataType:
-                return new DoubleDataType(constraints, false)
+                return new DoubleDataType(constraints, false, null)
 
             case StringDataType:
-                return new StringDataType(constraints, false)
+                return new StringDataType(constraints, false, null)
 
             case MappedCollectionDataType:
                 return new MappedCollectionDataType(
diff --git a/openapi-processor-core/src/test/groovy/com/github/hauner/openapi/core/writer/java/DataTypeWriterSpec.groovy b/openapi-processor-core/src/test/groovy/com/github/hauner/openapi/core/writer/java/DataTypeWriterSpec.groovy
diff --git a/openapi-processor-core/src/test/groovy/com/github/hauner/openapi/core/writer/java/MethodWriterSpec.groovy b/openapi-processor-core/src/test/groovy/com/github/hauner/openapi/core/writer/java/MethodWriterSpec.groovy
diff --git a/openapi-processor-core/src/test/kotlin/io/openapiprocessor/core/writer/java/JavaDocWriterSpec.kt b/openapi-processor-core/src/test/kotlin/io/openapiprocessor/core/writer/java/JavaDocWriterSpec.kt
diff --git a/openapi-processor-core/src/testInt/resources/tests/javadoc/generated/model/Foo.java b/openapi-processor-core/src/testInt/resources/tests/javadoc/generated/model/Foo.java
