Skip to content

Commit

Permalink
docs: Update documenting-headers.mdx
Browse files Browse the repository at this point in the history
Remove duplicated section im comparison to messages
  • Loading branch information
timonback committed Jun 30, 2024
1 parent b5fbbed commit cdd5a08
Showing 1 changed file with 0 additions and 75 deletions.
75 changes: 0 additions & 75 deletions docs/configuration/documenting-headers.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -54,78 +54,3 @@ public void sendMessage(ExamplePayloadDto msg) {
// process
}
```

## Schema

Under the hood Springwolf relies on swagger-core `ModelConverters` to define the message schema.

By default, the type and example values for the properties are guessed.
The default Jackson `ModelResolver` supports schema definitions via `@Schema` to overwrite the property definitions.

### 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))

#### Usage

Add the following dependency:

<Tabs>
<TabItem value="Groovy" label="Groovy" default>
<CodeBlock language="groovy">{CodeSchemaGroovy}</CodeBlock>
</TabItem>
<TabItem value="Maven" label="Maven">
<CodeBlock language="xml">{CodeSchemaMaven}</CodeBlock>
</TabItem>
</Tabs>

Then, add the `@Schema` annotation to the payload class:

<!-- vale off -->
```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;
}
}
```
<!-- vale on -->

:::note
The `@AsyncMessage.description` field will always override the `@Schema` description if provided
:::

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)

#### 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.

```java
@AsyncListener( operation = @AsyncOperation( channelName = TOPIC,
payloadType = StringEnvelope.class) // <- envelope class
)
public void receiveStringPayload(String stringPayload) { // <- The original class is used here
// ...
}

@Data
static class StringEnvelope {
@AsyncApiPayload // <- The annotation marker
@Schema(description = "Payload description using @Schema annotation and @AsyncApiPayload within envelope class")
private final String payload;
}
```

:::info
See [Add-Ons](../add-ons) for more information on how to document other formats
:::

0 comments on commit cdd5a08

Please sign in to comment.