Documentation of how to define Extension Fields for AsyncAPI (#63)

springwolf · Oct 30, 2023 · 3b94a73 · 3b94a73
1 parent abf338f
commit 3b94a73
Show file tree

Hide file tree

Showing 3 changed files with 18 additions and 5 deletions.
diff --git a/docs/configuration/configuration.md b/docs/configuration/configuration.md
@@ -55,6 +55,15 @@ An AsyncAPI document can contain more than one server, but it's not common.
 
 As with the `Info` object, all provided fields will be present in the generated document, but not all will be displayed in the UI.
 
+### Extension Fields
+
+The AsyncAPI specification allows the definition of additional data fields to extend the
+specification at certain points (see [Specification Extensions][extensions]).
+
+Extension Fields may be added to `Info`, `Contact`, `License` and `Server` objects both via `application.properties`
+or (deprecated) `AsyncApiDocket` . Every custom extension field must begin with `x-`, for example `x-internal-id`
+(see sample configurations above).
+
 ## Additional `application.properties`
 
 The following table contains additional properties that can be specified in the `application.properties` file:
@@ -107,7 +116,8 @@ the exposed AsyncAPI document will follow accordingly.
 Enabling actuator support for Springwolf will break the Springwolf UI.
 
 
-[identifier]: https://www.asyncapi.com/docs/reference/specification/v2.0.0#A2SIdString.
-[info]: https://www.asyncapi.com/docs/reference/specification/v2.0.0#infoObject.
-[server]: https://www.asyncapi.com/docs/reference/specification/v2.0.0#serversObject
-[default-content-type]: https://www.asyncapi.com/docs/reference/specification/v2.0.0#defaultContentTypeString
+[identifier]: https://www.asyncapi.com/docs/reference/specification/v2.6.0#A2SIdString.
+[info]: https://www.asyncapi.com/docs/reference/specification/v2.6.0#infoObject.
+[server]: https://www.asyncapi.com/docs/reference/specification/v2.6.0#serversObject
+[default-content-type]: https://www.asyncapi.com/docs/reference/specification/v2.6.0#defaultContentTypeString
+[extensions]: https://www.asyncapi.com/docs/reference/specification/v2.6.0#specificationExtensions
diff --git a/docs/configuration/snippets/_configuration_asyncApiDocket.java b/docs/configuration/snippets/_configuration_asyncApiDocket.java
@@ -23,6 +23,8 @@ public AsyncApiDocket asyncApiDocket() {
                         .build())
                 .build();
 
+        info.setExtensionFields(Map.of("x-internal-id", "xyz-123"));
+
         return AsyncApiDocket.builder()
                 .basePackage("io.github.stavshamir.springwolf.example.consumers")
                 .info(info)

diff --git a/docs/configuration/snippets/_configuration_properties.properties b/docs/configuration/snippets/_configuration_properties.properties
@@ -10,6 +10,7 @@ springwolf.docket.info.contact.name=springwolf
 springwolf.docket.info.contact.email[email protected]
 springwolf.docket.info.contact.url=https://github.com/springwolf/springwolf-core
 springwolf.docket.info.license.name=Apache License 2.0
+springwolf.docket.info.x-internal-id=xyz-123
 
 springwolf.docket.servers.kafka.protocol=kafka
-springwolf.docket.servers.kafka.url=${spring.kafka.bootstrap-servers}
+springwolf.docket.servers.kafka.url=${spring.kafka.bootstrap-servers}