docs: Add section for consumer/producer headers

Author: stavshamir

docs/documenting-producers.md

@@ -25,6 +25,7 @@ public AsyncApiDocket asyncApiDocket() {
             .description("Optional. Customer uploaded an example payload")
             .operationBinding(ImmutableMap.of("kafka", new KafkaOperationBinding()))
             .payloadType(ExamplePayloadDto.class)
+            .headers(AsyncHeaders.NOT_USED)
             .build();
 
     return AsyncApiDocket.builder()
@@ -54,6 +55,13 @@ This property is used to discriminate the producer's protocol and provide protoc
 
 The class object of the payload that will be published to this channel.
 
+### Header
+
+Optional. The headers describing the metadata of the payload.
+By default, `AsyncHeaders.NOT_DOCUMENTED` is used to indicate that no explicit header documentation exists.
+Use `AsyncHeaders` to add your custom headers, use `AsyncHeaders.NOT_USED` if you do not use headers and `AsyncHeadersForCloudEventsBuilder` if your events follow the CloudEvent specification.
+
+
 ## `AmqpProducerData`
 
 The above Kafka `ProducerData` equivalent in `AmqpProducerData`:
@@ -100,6 +108,7 @@ The above Kafka `ProducerData` simplifies to the following `KafkaProducerData`:
         .topicName("example-producer-topic")
         .description("Optional. Customer uploaded an example payload")
         .payloadType(ExamplePayloadDto.class)
+        .headers(AsyncHeaders.NOT_USED)
         .build();
 ```
 
@@ -115,6 +124,12 @@ Optional. The description allows for human-friendly text to verbosely explain th
 
 The class object of the payload that will be published to this channel.
 
+### Headers
+
+The Kafka headers describing the metadata of the payload, more details in the generic ProducerData.
+
+The Springwolf Kafka plugin comes with a special `AsyncHeadersForSpringKafkaBuilder` to document the `__TypeId__` header of the spring-kafka dependency.
+
 ### Example
 
 See a full example [here](https://github.com/springwolf/springwolf-core/blob/master/springwolf-examples/springwolf-kafka-example/src/main/java/io/github/stavshamir/springwolf/example/configuration/AsyncApiConfiguration.java).

docs/manually-documenting-consumers.md

@@ -25,6 +25,7 @@ public AsyncApiDocket asyncApiDocket() {
             .description("Optional. Customer uploaded an example payload")
             .operationBinding(ImmutableMap.of("kafka", new KafkaOperationBinding()))
             .payloadType(ExamplePayloadDto.class)
+            .headers(AsyncHeaders.NOT_USED)
             .build();
 
     return AsyncApiDocket.builder()
@@ -54,6 +55,13 @@ This property is used to discriminate the consumer's protocol and provide protoc
 
 The class object of the payload that will be consumed from this channel.
 
+### Header
+
+Optional. The headers describing the metadata of the payload.
+By default, `AsyncHeaders.NOT_DOCUMENTED` is used to indicate that no explicit header documentation exists.
+Use `AsyncHeaders` to add your custom headers, use `AsyncHeaders.NOT_USED` if you do not use headers and `AsyncHeadersForCloudEventsBuilder` if your events follow the CloudEvent specification.
+
+
 ## `AmqpConsumerData`
 
 The above Kafka `ConsumerData` equivalent in `AmqpConsumerData`:
@@ -100,6 +108,7 @@ The above Kafka `ConsumerData` simplifies to the following `KafkaConsumerData`:
         .topicName("example-consumer-topic")
         .description("Optional. Customer uploaded an example payload")
         .payloadType(ExamplePayloadDto.class)
+        .headers(AsyncHeaders.NOT_USED)
         .build();
 ```
 
@@ -115,6 +124,13 @@ Optional. The description allows for human-friendly text to verbosely explain th
 
 The class object of the payload that will be consumed from this channel.
 
+### Headers
+
+The Kafka headers describing the metadata of the payload, more details in the generic ConsumerData.
+
+The Springwolf Kafka plugin comes with a special `AsyncHeadersForSpringKafkaBuilder` to document the `__TypeId__` header of the spring-kafka dependency.
+
+
 ### Example
 
 See a full example [here](https://github.com/springwolf/springwolf-core/blob/master/springwolf-examples/springwolf-kafka-example/src/main/java/io/github/stavshamir/springwolf/example/configuration/AsyncApiConfiguration.java).