From 6af1878ff244e44bbe3d0948920ac4c4c018c6a4 Mon Sep 17 00:00:00 2001 From: Timon Back Date: Fri, 13 Jun 2025 15:31:42 +0200 Subject: [PATCH] docs: document usage of Schema annotation in Kotlin --- docs/configuration/documenting-headers.mdx | 6 --- docs/configuration/documenting-messages.mdx | 43 +++++++++---------- ...radle => _schema_dependency_groovy.gradle} | 2 +- ...maven.xml => _schema_dependency_maven.xml} | 2 +- docs/configuration/snippets/_schema_java.java | 12 ++++++ docs/configuration/snippets/_schema_kotlin.kt | 11 +++++ 6 files changed, 46 insertions(+), 30 deletions(-) rename docs/configuration/snippets/{_schema_groovy.gradle => _schema_dependency_groovy.gradle} (95%) rename docs/configuration/snippets/{_schema_maven.xml => _schema_dependency_maven.xml} (83%) create mode 100644 docs/configuration/snippets/_schema_java.java create mode 100644 docs/configuration/snippets/_schema_kotlin.kt diff --git a/docs/configuration/documenting-headers.mdx b/docs/configuration/documenting-headers.mdx index e3a2b10..bff0400 100644 --- a/docs/configuration/documenting-headers.mdx +++ b/docs/configuration/documenting-headers.mdx @@ -2,12 +2,6 @@ sidebar_position: 69 --- -import Tabs from '@theme/Tabs'; -import TabItem from '@theme/TabItem'; -import CodeBlock from '@theme/CodeBlock'; -import CodeSchemaGroovy from '!!raw-loader!./snippets/_schema_groovy.gradle'; -import CodeSchemaMaven from '!!raw-loader!./snippets/_schema_maven.xml'; - # Headers Springwolf provides different ways to document headers. The `header` is mapped to an AsyncAPI `schemaObject`. diff --git a/docs/configuration/documenting-messages.mdx b/docs/configuration/documenting-messages.mdx index 5baaef2..09a7462 100644 --- a/docs/configuration/documenting-messages.mdx +++ b/docs/configuration/documenting-messages.mdx @@ -5,8 +5,10 @@ sidebar_position: 68 import Tabs from '@theme/Tabs'; import TabItem from '@theme/TabItem'; import CodeBlock from '@theme/CodeBlock'; -import CodeSchemaGroovy from '!!raw-loader!./snippets/_schema_groovy.gradle'; -import CodeSchemaMaven from '!!raw-loader!./snippets/_schema_maven.xml'; +import CodeSchemaDependencyGroovy from '!!raw-loader!./snippets/_schema_dependency_groovy.gradle'; +import CodeSchemaDependencyMaven from '!!raw-loader!./snippets/_schema_dependency_maven.xml'; +import CodeSchemaJava from '!!raw-loader!./snippets/_schema_java.java'; +import CodeSchemaKotlin from '!!raw-loader!./snippets/_schema_kotlin.kt'; # Messages @@ -75,8 +77,9 @@ The default Jackson `ModelResolver` supports schema definitions via `@Schema` to ### Using `@Schema` The `@Schema` annotation allows to set many properties like `description`, `example`, `requiredMode`, `minimum` to document payloads. - -All properties are part of the produced AsyncAPI file. However, not all are displayed in `springwolf-ui` (see [#378](https://github.com/springwolf/springwolf-core/issues/378)) +Only properties that are part of [AsyncAPI spec](https://www.asyncapi.com/docs/reference/specification/v3.0.0#schemaObject) are part of the produced AsyncAPI file, +while the `@Schema` annotation contains some additional properties. +Contribute in [#378](https://github.com/springwolf/springwolf-core/issues/378), so that all properties are supported in `springwolf-ui`. #### Usage @@ -84,31 +87,23 @@ Add the following dependency: - {CodeSchemaGroovy} + {CodeSchemaDependencyGroovy} - {CodeSchemaMaven} + {CodeSchemaDependencyMaven} Then, add the `@Schema` annotation to the payload class: - -```java -import io.swagger.v3.oas.annotations.media.Schema; -import static io.swagger.v3.oas.annotations.media.Schema.RequiredMode.REQUIRED; - -@Schema(description = "Example payload model") -public class ExamplePayloadDto { - @Schema(description = "Some string field", example = "some string value", requiredMode = REQUIRED) - private String someString; - - public String getSomeString() { - return someString; - } -} -``` - + + + {CodeSchemaJava} + + + {CodeSchemaKotlin} + + :::note The `@AsyncMessage.description` field will always override the `@Schema` description if provided @@ -116,6 +111,10 @@ The `@AsyncMessage.description` field will always override the `@Schema` descrip For a full example, take a look at [ExamplePayloadDto.java in `springwolf-amqp-example`](https://github.com/springwolf/springwolf-core/blob/master/springwolf-examples/springwolf-amqp-example/src/main/java/io/github/springwolf/examples/amqp/dtos/ExamplePayloadDto.java) +#### Arrays using `@ArraySchema` + +When the payload is an array, use `@ArraySchema` annotation instead. + #### Primitive, final and external classes When the `@Schema` annotation can't be attached to the payload class (that's `java.lang.String`), the payload can be wrapped in an envelope class. The actual payload is a field within this class (`StringEnvelope`), marked using `@AsyncApiPayload` and documented using the `@Schema` annotation. diff --git a/docs/configuration/snippets/_schema_groovy.gradle b/docs/configuration/snippets/_schema_dependency_groovy.gradle similarity index 95% rename from docs/configuration/snippets/_schema_groovy.gradle rename to docs/configuration/snippets/_schema_dependency_groovy.gradle index 21c1abd..40146c5 100644 --- a/docs/configuration/snippets/_schema_groovy.gradle +++ b/docs/configuration/snippets/_schema_dependency_groovy.gradle @@ -1,3 +1,3 @@ dependencies { - implementation 'io.swagger.core.v3:swagger-core-jakarta:2.2.22' + implementation 'io.swagger.core.v3:swagger-core-jakarta:2.2.32' } diff --git a/docs/configuration/snippets/_schema_maven.xml b/docs/configuration/snippets/_schema_dependency_maven.xml similarity index 83% rename from docs/configuration/snippets/_schema_maven.xml rename to docs/configuration/snippets/_schema_dependency_maven.xml index 2e65884..fc744c0 100644 --- a/docs/configuration/snippets/_schema_maven.xml +++ b/docs/configuration/snippets/_schema_dependency_maven.xml @@ -2,6 +2,6 @@ io.swagger.core.v3 swagger-core-jakarta - 2.2.22 + 2.2.32 diff --git a/docs/configuration/snippets/_schema_java.java b/docs/configuration/snippets/_schema_java.java new file mode 100644 index 0000000..f8978e4 --- /dev/null +++ b/docs/configuration/snippets/_schema_java.java @@ -0,0 +1,12 @@ +import io.swagger.v3.oas.annotations.media.Schema; +import static io.swagger.v3.oas.annotations.media.Schema.RequiredMode.REQUIRED; + +@Schema(description = "Example payload model") +public class ExamplePayloadDto { + @Schema(description = "Some string field", example = "some string value", requiredMode = REQUIRED) + private String someString; + + public String getSomeString() { + return someString; + } +} \ No newline at end of file diff --git a/docs/configuration/snippets/_schema_kotlin.kt b/docs/configuration/snippets/_schema_kotlin.kt new file mode 100644 index 0000000..5f134e6 --- /dev/null +++ b/docs/configuration/snippets/_schema_kotlin.kt @@ -0,0 +1,11 @@ +import io.swagger.v3.oas.annotations.media.Schema +import io.swagger.v3.oas.annotations.media.Schema.RequiredMode.REQUIRED + +@Schema(description = "Example payload model") +public data class ExamplePayloadDto( + // The `@field:` annotation use-site target is important + @field:Schema(description = "Some string field", example = "some string value", requiredMode = REQUIRED) + public val someString: String, +) + +// Note: Kotlin inline value classes use mangling: https://kotlinlang.org/docs/inline-classes.html#mangling \ No newline at end of file