From 80d80068ac263bac8c486d70690947c954a09a4c Mon Sep 17 00:00:00 2001 From: vladi Date: Mon, 15 Apr 2024 14:01:00 +0200 Subject: [PATCH 01/14] init commit --- config/casestudies/hdi.yml | 140 ++++++++++++++++++++++++ public/img/casestudies/hdi/hdi_logo.svg | 19 ++++ 2 files changed, 159 insertions(+) create mode 100644 config/casestudies/hdi.yml create mode 100644 public/img/casestudies/hdi/hdi_logo.svg diff --git a/config/casestudies/hdi.yml b/config/casestudies/hdi.yml new file mode 100644 index 000000000000..b3cdd44bf36a --- /dev/null +++ b/config/casestudies/hdi.yml @@ -0,0 +1,140 @@ +id: hdiglobal +company: + name: HDI Global SE + description: The HDI brand is used in Germany and abroad by the life and property/casualty insurance companies, which focus on private and corporate customer business, as well as industrial insurance since 2016. + customers: XXXX + industry: Insurance + revenue: XXXX. + website: https://www.hdi.global/ + logo: /img/casestudies/hdi/hdi_logo.svg + contact: + - name: Vladislav Zwenihorodski + link: https://www.linkedin.com/in/vladislav-zwenihorodski-0b1b3b1b/ +challenges: | + + The HDI has various platform teams, among them the Integration Platform Team, which offers three products: API Management, Event Hub, and the Azure Service Bus. + For synchronous communication, we already use OpenAPI, as such we want to ensure the same level of transparency and discoverability for asynchronous scenarios as well. + Our central platform team offers the Azure Service Bus with self-service capabilities. + Customers are able to manage their own topics and subscribtions by simply modifying the according values in their repositories. + This means that most of the data required to document asynchronous communication is already available, although distributed between different repositories. + This necessitated the creation of a comprehensive catalog of existing topics, allowing potential subscribers easy access to messages from any topics of their choosing. + + +solution: | + The solution was to create an AsyncAPI document in which every topic owned by the customer is represented as a channel. + The document is automatically generated by a pipeline every time a change in Topic configuartion is applied. The necessary information is read from the customer repositories and then passed to a bash script as input. + After the successful creation this file as well as an generated markdown for it are safed within a documentation repository to ensure that the information is accessible for every developer. +technical: #We need some more technical information related to case study. + languages: + - bash + protocols: + - AMQP + architecture: | + The following [enterprise integration patterns](https://www.enterpriseintegrationpatterns.com/patterns/messaging) are applied : + - [Message Channel](https://www.enterpriseintegrationpatterns.com/patterns/messaging/MessageChannel.html) + Each channel in the AsyncAPI document represents an existing servicebus topic that can be subscribed to. + ``` + channels: + helloworld-emea: + servers: + - $ref: '#/servers/box-emea' + address: https://namespace.namespace/topic/example/helloworld + ``` + - [Message](https://www.enterpriseintegrationpatterns.com/patterns/messaging/Message.html) + - The 'messages' section under each channel in the AsyncAPI document represents this pattern. Each message has a name and a payload, which is the data transferred between applications. + ``` + messages: + helloworld: + name: helloworld-Message + contentType: application/json + payload: + $ref: "#/components/schemas/helloworld-topic-v1.json" + ``` + - [Document Message](https://www.enterpriseintegrationpatterns.com/patterns/messaging/DocumentMessage.html) + The 'payload' under each message in the AsyncAPI document represents this pattern. The payload is a self-contained document that describes the message and can be understood by the message receiver. + ``` + payload: + $ref: "#/components/schemas/helloworld-topic-v1.json" + ``` + In our repositoriy structure the message-schema file is stored seperatly and just referenced in the Topic configs. + To ensure that all information is accesible in one place, the schema is directly copied to the AsyncAPI document. + ``` + components: + schemas: + helloworld-topic-v1.json: { + "$schema": "http://json-schema.org/draft-06/schema#", + "type": "object", + "properties": { + "eventType": { + "type": "object", + "enum": [ + "create", + "update", + "delete" + ] + }, + "hotel": { + "type": "object", + "properties": { + "id": { + "type": "string" + }, + "name": { + "type": "string" + }, + "slogan": { + "type": "string" + }, + "location": { + "type": "string" + }, + "total_number_of_rooms": { + "type": "integer" + }, + "currently_available_rooms": { + "type": "integer" + }, + "currently_occupied_rooms": { + "type": "integer" + } + }, + "required": [ + "id", + "name" + ] + } + }, + "required": [ + "eventType", + "hotel" + ] + } + ``` + codegen: | + #Do you generate code from AsyncAPI? If yes, how do you do it? What tools do you use? +schemas: #It is useful and interesting to learn how teams handle messages schemas. + description: JSON Schema + storage: Git repository where customer can store their own config files for the service bus. + validation: Validated using [Ajv](https://ajv.js.org/) +asyncapi: #More specific details about AsyncAPI itself and how is it used. + usecase: | + - used for documentation purposes by the platform team + - used to genrate data transfer objects from the AsyncAPI yaml file + versions: + - 3.0 + storage: | + repositoriy for the customer wiki that describes the topics and the messages that can be subscribed to. + editing: | + If changes for any topic are applied by a customer the documentation pipline generates the AsyncAPI file using a bash script. + audience: #Specify if AsyncAPI audience is internal or external or both. + internal: true + external: false + documentation: | + Documentation is generated via AsyncAPI CLI and published to the wiki right after the AsyncAPI file is generated. + bindings: | + #Specify what bindings are used by their name and provide description on what level you use bindings. Provide examples if possible. + tools: | + * [AsyncAPI Generator](https://github.com/asyncapi/generator): + * [markdown-template](https://github.com/asyncapi/markdown-template). + fullExample: #Should be url to full example of the case study. So later in the UI we can show it as "https://studio.asyncapi.com/?url=https://deploy-preview-921--asyncapi-website.netlify.app/resources/casestudies/adeo/asyncapi.yaml" so the example can be previewed in the AsyncAPI Studio easily. +additionalResources: #Provide some additional resources if there are such. Just block of text with links to articles or videos about the case study. \ No newline at end of file diff --git a/public/img/casestudies/hdi/hdi_logo.svg b/public/img/casestudies/hdi/hdi_logo.svg new file mode 100644 index 000000000000..1c6d887161f9 --- /dev/null +++ b/public/img/casestudies/hdi/hdi_logo.svg @@ -0,0 +1,19 @@ + + + + 500x200 + Created with Sketch. + + + + + + + + + + + + + + \ No newline at end of file From 5208a9b9ecd0808af1a4999b20fe01bafb4a72d2 Mon Sep 17 00:00:00 2001 From: vladi Date: Mon, 15 Apr 2024 14:16:00 +0200 Subject: [PATCH 02/14] wip --- config/casestudies/hdi.yml | 6 ++++-- 1 file changed, 4 insertions(+), 2 deletions(-) diff --git a/config/casestudies/hdi.yml b/config/casestudies/hdi.yml index b3cdd44bf36a..b2f7a2036b44 100644 --- a/config/casestudies/hdi.yml +++ b/config/casestudies/hdi.yml @@ -27,6 +27,8 @@ solution: | technical: #We need some more technical information related to case study. languages: - bash + frameworks: + - # cant be removed is expected to exist protocols: - AMQP architecture: | @@ -123,7 +125,7 @@ asyncapi: #More specific details about AsyncAPI itself and how is it used. versions: - 3.0 storage: | - repositoriy for the customer wiki that describes the topics and the messages that can be subscribed to. + Git repositoriy that functions as "customer Wiki" where every relevant documents about the exiting infrastructure is stored . editing: | If changes for any topic are applied by a customer the documentation pipline generates the AsyncAPI file using a bash script. audience: #Specify if AsyncAPI audience is internal or external or both. @@ -132,7 +134,7 @@ asyncapi: #More specific details about AsyncAPI itself and how is it used. documentation: | Documentation is generated via AsyncAPI CLI and published to the wiki right after the AsyncAPI file is generated. bindings: | - #Specify what bindings are used by their name and provide description on what level you use bindings. Provide examples if possible. + none tools: | * [AsyncAPI Generator](https://github.com/asyncapi/generator): * [markdown-template](https://github.com/asyncapi/markdown-template). From c8960faa92edd64a4c96d2e485ffd0b26a6a01f0 Mon Sep 17 00:00:00 2001 From: vladi Date: Mon, 15 Apr 2024 14:33:00 +0200 Subject: [PATCH 03/14] added full yml and return of fields that cant be removed --- config/casestudies/hdi.yml | 8 +- .../resources/casestudies/hdi/asyncapi.yaml | 151 ++++++++++++++++++ 2 files changed, 158 insertions(+), 1 deletion(-) create mode 100644 public/resources/casestudies/hdi/asyncapi.yaml diff --git a/config/casestudies/hdi.yml b/config/casestudies/hdi.yml index b2f7a2036b44..70c71fba3c18 100644 --- a/config/casestudies/hdi.yml +++ b/config/casestudies/hdi.yml @@ -117,6 +117,8 @@ technical: #We need some more technical information related to case study. schemas: #It is useful and interesting to learn how teams handle messages schemas. description: JSON Schema storage: Git repository where customer can store their own config files for the service bus. + registry: #Are you using schema registry solution? which one? cant be removed + versioning: #How do you handle versioning of schemas? cant be removed validation: Validated using [Ajv](https://ajv.js.org/) asyncapi: #More specific details about AsyncAPI itself and how is it used. usecase: | @@ -128,9 +130,13 @@ asyncapi: #More specific details about AsyncAPI itself and how is it used. Git repositoriy that functions as "customer Wiki" where every relevant documents about the exiting infrastructure is stored . editing: | If changes for any topic are applied by a customer the documentation pipline generates the AsyncAPI file using a bash script. + maintainers: | + none audience: #Specify if AsyncAPI audience is internal or external or both. internal: true external: false + extensions: | + none documentation: | Documentation is generated via AsyncAPI CLI and published to the wiki right after the AsyncAPI file is generated. bindings: | @@ -138,5 +144,5 @@ asyncapi: #More specific details about AsyncAPI itself and how is it used. tools: | * [AsyncAPI Generator](https://github.com/asyncapi/generator): * [markdown-template](https://github.com/asyncapi/markdown-template). - fullExample: #Should be url to full example of the case study. So later in the UI we can show it as "https://studio.asyncapi.com/?url=https://deploy-preview-921--asyncapi-website.netlify.app/resources/casestudies/adeo/asyncapi.yaml" so the example can be previewed in the AsyncAPI Studio easily. + fullExample: resources/casestudies/hdi/asyncapi.yaml additionalResources: #Provide some additional resources if there are such. Just block of text with links to articles or videos about the case study. \ No newline at end of file diff --git a/public/resources/casestudies/hdi/asyncapi.yaml b/public/resources/casestudies/hdi/asyncapi.yaml new file mode 100644 index 000000000000..2037540565a7 --- /dev/null +++ b/public/resources/casestudies/hdi/asyncapi.yaml @@ -0,0 +1,151 @@ +asyncapi: 3.0.0 +info: + title: customer-example + version: 1.0.0 + description: | + This is an AsyncAPI document for customer-example. + It contains every Topic owned by the customer in form of channel. + Dowload the coresponding schema files from the following link: +servers: + box-apac: + host: namespace.servicebus.windows.net + protocol: amqp + description: Azure Service Bus namespace endpoint for box. + box-emea: + host: namespace.servicebus.windows.net + protocol: amqp + description: Azure Service Bus namespace endpoint for box. +channels: + helloworld-emea: + servers: + - $ref: '#/servers/box-emea' + address: https://namespace.servicebus.windows.net/topic/example/helloworld + messages: + helloworld: + name: helloworld-Message + contentType: application/json + payload: + $ref: '#/components/schemas/helloworld-topic-v1.json' + test-topic-emea: + servers: + - $ref: '#/servers/box-emea' + address: https://namespace.servicebus.windows.net/topic/example/test-topic + messages: + test-topic: + name: test-topic-Message + contentType: application/json + payload: + $ref: '#/components/schemas/test-topic-v1.json' + test-pipeline-emea: + servers: + - $ref: '#/servers/box-emea' + address: https://namespace.servicebus.windows.net/topic/example/test-pipeline + messages: + test-pipeline: + name: test-pipeline-Message + contentType: application/json + payload: + $ref: '#/components/schemas/test-topic-v1.json' + source1-emea: + servers: + - $ref: '#/servers/box-emea' + address: https://namespace.servicebus.windows.net/topic/example/source1 + messages: + source1: + name: source1-Message + contentType: application/json + payload: + $ref: '#/components/schemas/test-topic-v1.json' +operations: + helloworld-emea: + action: send + channel: + $ref: '#/channels/helloworld-emea' + messages: + - $ref: '#/channels/helloworld-emea/messages/helloworld' + test-topic-emea: + action: send + channel: + $ref: '#/channels/test-topic-emea' + messages: + - $ref: '#/channels/test-topic-emea/messages/test-topic' + test-pipeline-emea: + action: send + channel: + $ref: '#/channels/test-pipeline-emea' + messages: + - $ref: '#/channels/test-pipeline-emea/messages/test-pipeline' + source1-emea: + action: send + channel: + $ref: '#/channels/source1-emea' + messages: + - $ref: '#/channels/source1-emea/messages/source1' +components: + schemas: + test-topic-v1.json: + $schema: http://json-schema.org/draft-06/schema# + type: object + properties: + eventType: + type: object + enum: + - create + - update + - delete + hotel: + type: object + properties: + id: + type: string + name: + type: string + slogan: + type: string + location: + type: string + total_number_of_rooms: + type: integer + currently_available_rooms: + type: integer + currently_occupied_rooms: + type: integer + required: + - id + - name + required: + - eventType + - hotel + helloworld-topic-v1.json: + $schema: http://json-schema.org/draft-06/schema# + type: object + properties: + eventType: + type: object + enum: + - create + - update + - delete + hotel: + type: object + properties: + id: + type: string + name: + type: string + slogan: + type: string + location: + type: string + total_number_of_rooms: + type: integer + currently_available_rooms: + type: integer + currently_occupied_rooms: + type: integer + required: + - id + - name + required: + - eventType + - hotel From 42a220b897ca7c993f3904a525d519153d25b004 Mon Sep 17 00:00:00 2001 From: vladi Date: Fri, 31 May 2024 09:57:39 +0200 Subject: [PATCH 04/14] rework --- config/casestudies/hdi.yml | 61 +++++++++++++++++++++++--------------- 1 file changed, 37 insertions(+), 24 deletions(-) diff --git a/config/casestudies/hdi.yml b/config/casestudies/hdi.yml index 70c71fba3c18..58a18a16585a 100644 --- a/config/casestudies/hdi.yml +++ b/config/casestudies/hdi.yml @@ -1,29 +1,31 @@ id: hdiglobal company: name: HDI Global SE - description: The HDI brand is used in Germany and abroad by the life and property/casualty insurance companies, which focus on private and corporate customer business, as well as industrial insurance since 2016. - customers: XXXX + description: The HDI brand operates in Germany and internationally, offering life and property/casualty insurance services. They cater to both private individuals and corporate clients, and have been providing industrial insurance since 2016. + customers: 5000 industry: Insurance - revenue: XXXX. + revenue: 9.1 Mrd. EUR website: https://www.hdi.global/ logo: /img/casestudies/hdi/hdi_logo.svg contact: - name: Vladislav Zwenihorodski - link: https://www.linkedin.com/in/vladislav-zwenihorodski-0b1b3b1b/ + link: https://www.linkedin.com/in/vladislav-zwenihorodski-9680a1209/ challenges: | - The HDI has various platform teams, among them the Integration Platform Team, which offers three products: API Management, Event Hub, and the Azure Service Bus. For synchronous communication, we already use OpenAPI, as such we want to ensure the same level of transparency and discoverability for asynchronous scenarios as well. Our central platform team offers the Azure Service Bus with self-service capabilities. - Customers are able to manage their own topics and subscribtions by simply modifying the according values in their repositories. + Customers are able to manage their own topics and subscriptions by simply modifying the according values in their repositories. This means that most of the data required to document asynchronous communication is already available, although distributed between different repositories. This necessitated the creation of a comprehensive catalog of existing topics, allowing potential subscribers easy access to messages from any topics of their choosing. solution: | - The solution was to create an AsyncAPI document in which every topic owned by the customer is represented as a channel. - The document is automatically generated by a pipeline every time a change in Topic configuartion is applied. The necessary information is read from the customer repositories and then passed to a bash script as input. - After the successful creation this file as well as an generated markdown for it are safed within a documentation repository to ensure that the information is accessible for every developer. + The solution was to create an an AsyncAPI document where each topic owned by the customer is represented as a channel. + This document is automatically generated by a pipeline whenever there's a change in the topic configuration. + The necessary information is read from the customer repositories and then passed to a bash script as input. + After successful creation, this file, along with a generated markdown for it, is saved within a documentation repository. + This ensures that the information is readily accessible to every developer, allowing easy access to messages from any topics of their choosing. + This approach makes our asynchronous communication is as transparent and discoverable as our synchronous communication. technical: #We need some more technical information related to case study. languages: - bash @@ -31,10 +33,12 @@ technical: #We need some more technical information related to case study. - # cant be removed is expected to exist protocols: - AMQP + testing: | + The AsyncAPI document is validated using the AsyncAPI CLI to confirm that the document is correctly formatted and adheres to the AsyncAPI specification. architecture: | The following [enterprise integration patterns](https://www.enterpriseintegrationpatterns.com/patterns/messaging) are applied : - [Message Channel](https://www.enterpriseintegrationpatterns.com/patterns/messaging/MessageChannel.html) - Each channel in the AsyncAPI document represents an existing servicebus topic that can be subscribed to. + Each channel in the AsyncAPI document corresponds to an existing Service Bus topic that can be subscribed to. ``` channels: helloworld-emea: @@ -43,7 +47,8 @@ technical: #We need some more technical information related to case study. address: https://namespace.namespace/topic/example/helloworld ``` - [Message](https://www.enterpriseintegrationpatterns.com/patterns/messaging/Message.html) - - The 'messages' section under each channel in the AsyncAPI document represents this pattern. Each message has a name and a payload, which is the data transferred between applications. + The 'messages' section under each channel in the AsyncAPI document adheres to this pattern. + Each message is identified by a name and contains a payload, which represents the data transferred between applications. ``` messages: helloworld: @@ -53,13 +58,14 @@ technical: #We need some more technical information related to case study. $ref: "#/components/schemas/helloworld-topic-v1.json" ``` - [Document Message](https://www.enterpriseintegrationpatterns.com/patterns/messaging/DocumentMessage.html) - The 'payload' under each message in the AsyncAPI document represents this pattern. The payload is a self-contained document that describes the message and can be understood by the message receiver. + The 'payload' under each message in the AsyncAPI document adheres to this pattern. + The payload is a self-contained document that describes the message and is comprehensible to the message receiver. ``` payload: $ref: "#/components/schemas/helloworld-topic-v1.json" ``` - In our repositoriy structure the message-schema file is stored seperatly and just referenced in the Topic configs. - To ensure that all information is accesible in one place, the schema is directly copied to the AsyncAPI document. + In our repository structure, the message-schema file is stored separately and just referenced in the Topic configs. + To make sure that all information is accessible in one place, the schema is directly copied to the AsyncAPI document. ``` components: schemas: @@ -113,25 +119,32 @@ technical: #We need some more technical information related to case study. } ``` codegen: | - #Do you generate code from AsyncAPI? If yes, how do you do it? What tools do you use? + #Explain if you use code generation, what you generate and how. Provide examples if possible. schemas: #It is useful and interesting to learn how teams handle messages schemas. description: JSON Schema - storage: Git repository where customer can store their own config files for the service bus. - registry: #Are you using schema registry solution? which one? cant be removed - versioning: #How do you handle versioning of schemas? cant be removed - validation: Validated using [Ajv](https://ajv.js.org/) + storage: A Git repository functions as a self-service portal where customers can manage their own configurations for the Azure Service Bus. + This includes defining their own message schemas for any topics they own. + registry: none + versioning: The customer has the freedom to choose the versioning for their own message-schema files. + validation: Validation using [Ajv](https://ajv.js.org/), is used solely for the purpose of validating that the JSON data adheres to the expected schema. + It does not perform any other form of validation or processing of the data. asyncapi: #More specific details about AsyncAPI itself and how is it used. usecase: | - - used for documentation purposes by the platform team - - used to genrate data transfer objects from the AsyncAPI yaml file + - The AsyncAPI file is used for documentation purposes by the platform team. + It provides a comprehensive overview of the asynchronous communication in our system, including the available topics and the structure of the messages. + - The AsyncAPI document serves as a source for generating data transfer objects (DTOs) in Java, for example, by using the AsyncAPI Java generator. + These DTOs are used in the code to ensure type safety and to provide a clear understanding of the data structure. versions: - 3.0 storage: | - Git repositoriy that functions as "customer Wiki" where every relevant documents about the exiting infrastructure is stored . + A seperate Git repository functions as a "customer Wiki", serving as a central location for all relevant documents about the existing infrastructure. + This includes the AsyncAPI document, which provides a comprehensive overview of the asynchronous communication in our system. editing: | - If changes for any topic are applied by a customer the documentation pipline generates the AsyncAPI file using a bash script. + If changes for any topic are applied by a customer, the documentation pipeline is triggered. + This pipeline uses a bash script to read the updated configuration from the customer's repository. + It then generates a new AsyncAPI file reflecting these changes. maintainers: | - none + No specific maintainers are assigned to the AsyncAPI document. The document is automatically generated by a pipeline. audience: #Specify if AsyncAPI audience is internal or external or both. internal: true external: false From d7c54756b22e95ab355fa21a38f52261a6273530 Mon Sep 17 00:00:00 2001 From: vladi Date: Fri, 31 May 2024 10:05:03 +0200 Subject: [PATCH 05/14] wip --- config/casestudies/hdi.yml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/config/casestudies/hdi.yml b/config/casestudies/hdi.yml index 58a18a16585a..397bc45003c4 100644 --- a/config/casestudies/hdi.yml +++ b/config/casestudies/hdi.yml @@ -11,7 +11,7 @@ company: - name: Vladislav Zwenihorodski link: https://www.linkedin.com/in/vladislav-zwenihorodski-9680a1209/ challenges: | - The HDI has various platform teams, among them the Integration Platform Team, which offers three products: API Management, Event Hub, and the Azure Service Bus. + The HDI has various platform teams, among them the Integration Platform Team, which offers three products: Azure API Management, Azure Event Hub, and the Azure Service Bus. For synchronous communication, we already use OpenAPI, as such we want to ensure the same level of transparency and discoverability for asynchronous scenarios as well. Our central platform team offers the Azure Service Bus with self-service capabilities. Customers are able to manage their own topics and subscriptions by simply modifying the according values in their repositories. From 6b4d9fb83fc23d9182121d8682c7b237edc0cd3c Mon Sep 17 00:00:00 2001 From: vladi Date: Fri, 31 May 2024 10:39:31 +0200 Subject: [PATCH 06/14] wip --- config/casestudies/hdi.yml | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/config/casestudies/hdi.yml b/config/casestudies/hdi.yml index 397bc45003c4..cd09c265458e 100644 --- a/config/casestudies/hdi.yml +++ b/config/casestudies/hdi.yml @@ -119,7 +119,8 @@ technical: #We need some more technical information related to case study. } ``` codegen: | - #Explain if you use code generation, what you generate and how. Provide examples if possible. + Our team does not use code generation tools. + However, our customers are free to use any tool they prefer to generate DTOs from the AsyncAPI document. schemas: #It is useful and interesting to learn how teams handle messages schemas. description: JSON Schema storage: A Git repository functions as a self-service portal where customers can manage their own configurations for the Azure Service Bus. From 0616344bb0262ec1ab594c32d44be84c314f1121 Mon Sep 17 00:00:00 2001 From: Lukasz Gornicki Date: Fri, 31 May 2024 21:43:36 +0200 Subject: [PATCH 07/14] removing empty key to fix failing build --- config/casestudies/hdi.yml | 1 - 1 file changed, 1 deletion(-) diff --git a/config/casestudies/hdi.yml b/config/casestudies/hdi.yml index cd09c265458e..22684a7fd584 100644 --- a/config/casestudies/hdi.yml +++ b/config/casestudies/hdi.yml @@ -159,4 +159,3 @@ asyncapi: #More specific details about AsyncAPI itself and how is it used. * [AsyncAPI Generator](https://github.com/asyncapi/generator): * [markdown-template](https://github.com/asyncapi/markdown-template). fullExample: resources/casestudies/hdi/asyncapi.yaml -additionalResources: #Provide some additional resources if there are such. Just block of text with links to articles or videos about the case study. \ No newline at end of file From d9aa032dbaa2f9f18ac4309c4692131510bb4d7b Mon Sep 17 00:00:00 2001 From: Lukasz Gornicki Date: Fri, 31 May 2024 21:45:55 +0200 Subject: [PATCH 08/14] additionalResources set to null --- config/casestudies/hdi.yml | 1 + 1 file changed, 1 insertion(+) diff --git a/config/casestudies/hdi.yml b/config/casestudies/hdi.yml index 22684a7fd584..4dffbda081a8 100644 --- a/config/casestudies/hdi.yml +++ b/config/casestudies/hdi.yml @@ -159,3 +159,4 @@ asyncapi: #More specific details about AsyncAPI itself and how is it used. * [AsyncAPI Generator](https://github.com/asyncapi/generator): * [markdown-template](https://github.com/asyncapi/markdown-template). fullExample: resources/casestudies/hdi/asyncapi.yaml +additionalResources: null From 153fe35cc04cc3c3fc70888c307f1350b571416a Mon Sep 17 00:00:00 2001 From: Lukasz Gornicki Date: Fri, 31 May 2024 22:06:57 +0200 Subject: [PATCH 09/14] adding more fixes to failing build --- config/casestudies/hdi.yml | 9 +++++---- 1 file changed, 5 insertions(+), 4 deletions(-) diff --git a/config/casestudies/hdi.yml b/config/casestudies/hdi.yml index 4dffbda081a8..9c44c24d2b3b 100644 --- a/config/casestudies/hdi.yml +++ b/config/casestudies/hdi.yml @@ -2,7 +2,7 @@ id: hdiglobal company: name: HDI Global SE description: The HDI brand operates in Germany and internationally, offering life and property/casualty insurance services. They cater to both private individuals and corporate clients, and have been providing industrial insurance since 2016. - customers: 5000 + customers: "5000" industry: Insurance revenue: 9.1 Mrd. EUR website: https://www.hdi.global/ @@ -30,9 +30,10 @@ technical: #We need some more technical information related to case study. languages: - bash frameworks: - - # cant be removed is expected to exist + - Nothing specific protocols: - AMQP + broker: Azure Service Bus testing: | The AsyncAPI document is validated using the AsyncAPI CLI to confirm that the document is correctly formatted and adheres to the AsyncAPI specification. architecture: | @@ -136,7 +137,7 @@ asyncapi: #More specific details about AsyncAPI itself and how is it used. - The AsyncAPI document serves as a source for generating data transfer objects (DTOs) in Java, for example, by using the AsyncAPI Java generator. These DTOs are used in the code to ensure type safety and to provide a clear understanding of the data structure. versions: - - 3.0 + - '3.0.0' storage: | A seperate Git repository functions as a "customer Wiki", serving as a central location for all relevant documents about the existing infrastructure. This includes the AsyncAPI document, which provides a comprehensive overview of the asynchronous communication in our system. @@ -159,4 +160,4 @@ asyncapi: #More specific details about AsyncAPI itself and how is it used. * [AsyncAPI Generator](https://github.com/asyncapi/generator): * [markdown-template](https://github.com/asyncapi/markdown-template). fullExample: resources/casestudies/hdi/asyncapi.yaml -additionalResources: null +additionalResources: ' ' From 12a383fbe27ecf5387bf3abbba73f5c4c1251930 Mon Sep 17 00:00:00 2001 From: Lukasz Gornicki Date: Fri, 31 May 2024 22:12:29 +0200 Subject: [PATCH 10/14] brokers instead of broker --- config/casestudies/hdi.yml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/config/casestudies/hdi.yml b/config/casestudies/hdi.yml index 9c44c24d2b3b..eb37a355f8ed 100644 --- a/config/casestudies/hdi.yml +++ b/config/casestudies/hdi.yml @@ -33,7 +33,7 @@ technical: #We need some more technical information related to case study. - Nothing specific protocols: - AMQP - broker: Azure Service Bus + brokers: Azure Service Bus testing: | The AsyncAPI document is validated using the AsyncAPI CLI to confirm that the document is correctly formatted and adheres to the AsyncAPI specification. architecture: | From 43f217bcb771b82bafc6ce72eb2ab8a105fd9d5a Mon Sep 17 00:00:00 2001 From: vlazw <166604035+vlazw@users.noreply.github.com> Date: Thu, 13 Jun 2024 10:41:39 +0200 Subject: [PATCH 11/14] Update config/casestudies/hdi.yml Co-authored-by: Lukasz Gornicki --- config/casestudies/hdi.yml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/config/casestudies/hdi.yml b/config/casestudies/hdi.yml index eb37a355f8ed..c79aaf131553 100644 --- a/config/casestudies/hdi.yml +++ b/config/casestudies/hdi.yml @@ -132,7 +132,7 @@ schemas: #It is useful and interesting to learn how teams handle messages schema It does not perform any other form of validation or processing of the data. asyncapi: #More specific details about AsyncAPI itself and how is it used. usecase: | - - The AsyncAPI file is used for documentation purposes by the platform team. + - The AsyncAPI documents are used for documentation purposes by the platform team. It provides a comprehensive overview of the asynchronous communication in our system, including the available topics and the structure of the messages. - The AsyncAPI document serves as a source for generating data transfer objects (DTOs) in Java, for example, by using the AsyncAPI Java generator. These DTOs are used in the code to ensure type safety and to provide a clear understanding of the data structure. From 295cb4df37d29d8cf98ed79dbceb812e1497a26a Mon Sep 17 00:00:00 2001 From: vlazw <166604035+vlazw@users.noreply.github.com> Date: Thu, 13 Jun 2024 10:41:49 +0200 Subject: [PATCH 12/14] Update config/casestudies/hdi.yml Co-authored-by: Lukasz Gornicki --- config/casestudies/hdi.yml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/config/casestudies/hdi.yml b/config/casestudies/hdi.yml index c79aaf131553..4440bc37087f 100644 --- a/config/casestudies/hdi.yml +++ b/config/casestudies/hdi.yml @@ -144,7 +144,7 @@ asyncapi: #More specific details about AsyncAPI itself and how is it used. editing: | If changes for any topic are applied by a customer, the documentation pipeline is triggered. This pipeline uses a bash script to read the updated configuration from the customer's repository. - It then generates a new AsyncAPI file reflecting these changes. + It then generates a new AsyncAPI document reflecting these changes. maintainers: | No specific maintainers are assigned to the AsyncAPI document. The document is automatically generated by a pipeline. audience: #Specify if AsyncAPI audience is internal or external or both. From 2c5d9e725a79aaa3aa50e63121ec8ba8866019c1 Mon Sep 17 00:00:00 2001 From: vladi Date: Thu, 4 Jul 2024 15:24:08 +0200 Subject: [PATCH 13/14] reworked schema example --- config/casestudies/hdi.yml | 163 ++++++--- .../resources/casestudies/hdi/asyncapi.yaml | 345 ++++++++++++------ 2 files changed, 345 insertions(+), 163 deletions(-) diff --git a/config/casestudies/hdi.yml b/config/casestudies/hdi.yml index 4440bc37087f..f4fdb42094c9 100644 --- a/config/casestudies/hdi.yml +++ b/config/casestudies/hdi.yml @@ -24,103 +24,168 @@ solution: | This document is automatically generated by a pipeline whenever there's a change in the topic configuration. The necessary information is read from the customer repositories and then passed to a bash script as input. After successful creation, this file, along with a generated markdown for it, is saved within a documentation repository. + This documentation repository serves as the basis for our Azure DevOps wiki, ensuring that all project documentation is centralized and easily accessible. This ensures that the information is readily accessible to every developer, allowing easy access to messages from any topics of their choosing. This approach makes our asynchronous communication is as transparent and discoverable as our synchronous communication. technical: #We need some more technical information related to case study. languages: - - bash + - java, .net, bash frameworks: - - Nothing specific + - Spring Boot protocols: - AMQP brokers: Azure Service Bus testing: | - The AsyncAPI document is validated using the AsyncAPI CLI to confirm that the document is correctly formatted and adheres to the AsyncAPI specification. + The AsyncAPI document is validated using the AsyncAPI CLI to confirm that the document is correctly formatted and adheres to the AsyncAPI specification right after creation and befor being commited to the documentation repository. architecture: | The following [enterprise integration patterns](https://www.enterpriseintegrationpatterns.com/patterns/messaging) are applied : - [Message Channel](https://www.enterpriseintegrationpatterns.com/patterns/messaging/MessageChannel.html) Each channel in the AsyncAPI document corresponds to an existing Service Bus topic that can be subscribed to. ``` channels: - helloworld-emea: - servers: + claimStatus-emea: + servers: - $ref: '#/servers/box-emea' - address: https://namespace.namespace/topic/example/helloworld + address: https://namespace.servicebus.windows.net/topic/example/claimStatus ``` - [Message](https://www.enterpriseintegrationpatterns.com/patterns/messaging/Message.html) The 'messages' section under each channel in the AsyncAPI document adheres to this pattern. Each message is identified by a name and contains a payload, which represents the data transferred between applications. ``` messages: - helloworld: - name: helloworld-Message + claimStatus: + name: claimStatus-Message contentType: application/json - payload: - $ref: "#/components/schemas/helloworld-topic-v1.json" ``` - [Document Message](https://www.enterpriseintegrationpatterns.com/patterns/messaging/DocumentMessage.html) The 'payload' under each message in the AsyncAPI document adheres to this pattern. The payload is a self-contained document that describes the message and is comprehensible to the message receiver. ``` payload: - $ref: "#/components/schemas/helloworld-topic-v1.json" + $ref: '#/components/schemas/claimStatus-example.json' ``` In our repository structure, the message-schema file is stored separately and just referenced in the Topic configs. To make sure that all information is accessible in one place, the schema is directly copied to the AsyncAPI document. ``` components: schemas: - helloworld-topic-v1.json: { + claimStatus-example.json: { "$schema": "http://json-schema.org/draft-06/schema#", "type": "object", "properties": { - "eventType": { - "type": "object", - "enum": [ - "create", - "update", - "delete" - ] - }, - "hotel": { + "message": { "type": "object", "properties": { - "id": { - "type": "string" - }, - "name": { - "type": "string" - }, - "slogan": { - "type": "string" - }, - "location": { + "version": { "type": "string" }, - "total_number_of_rooms": { - "type": "integer" + "header": { + "type": "object", + "properties": { + "messageId": { + "type": "string" + }, + "entityType": { + "type": "string" + }, + "eventType": { + "type": "object", + "enum": [ + "create", + "update" + ] + } + }, + "required": [ + "messageId", + "entityType", + "eventType" + ] }, - "currently_available_rooms": { - "type": "integer" - }, - "currently_occupied_rooms": { - "type": "integer" + "data": { + "type": "object", + "properties": { + "par": { + "type": "object", + "properties": { + "tenantNumber": { + "type": "string" + }, + "policyNumber": { + "type": "number" + }, + "contractNumber": { + "type": "number" + }, + "sourceSystem": { + "type": "string" + }, + "claimStatus": { + "type": "string" + }, + "currencyCode": { + "type": "string" + }, + "registrYear": { + "type": "number" + }, + "broker": { + "type": "string" + }, + "insured": { + "type": "string" + }, + "lineOfBusiness": { + "type": "number" + }, + "claimCountry": { + "type": "string" + }, + "isNewClaim": { + "type": "boolean" + }, + "dateOfLoss": { + "type": "string", + "format": "date" + }, + "creationDate": { + "type": "string", + "format": "date" + }, + "notificationDate": { + "type": "string", + "format": "date" + }, + "businessDate": { + "type": "string", + "format": "date" + } + }, + "required": [ + "tenantNumber" + ] + } + }, + "required": [ + "par" + ] } }, "required": [ - "id", - "name" + "version", + "header", + "data" ] } }, "required": [ - "eventType", - "hotel" + "message" ] } + ``` codegen: | - Our team does not use code generation tools. + Our team currently does not use or ofer a code generation tool. However, our customers are free to use any tool they prefer to generate DTOs from the AsyncAPI document. schemas: #It is useful and interesting to learn how teams handle messages schemas. description: JSON Schema @@ -128,14 +193,13 @@ schemas: #It is useful and interesting to learn how teams handle messages schema This includes defining their own message schemas for any topics they own. registry: none versioning: The customer has the freedom to choose the versioning for their own message-schema files. - validation: Validation using [Ajv](https://ajv.js.org/), is used solely for the purpose of validating that the JSON data adheres to the expected schema. - It does not perform any other form of validation or processing of the data. + validation: Validation using [Ajv](https://ajv.js.org/) is used solely for the purpose of ensuring that the JSON data adheres to the expected schema. This validation is performed for each customer by the Pull Request pipeline we provide. + It does not perform any other form of validation or processing on the data. asyncapi: #More specific details about AsyncAPI itself and how is it used. usecase: | - The AsyncAPI documents are used for documentation purposes by the platform team. It provides a comprehensive overview of the asynchronous communication in our system, including the available topics and the structure of the messages. - - The AsyncAPI document serves as a source for generating data transfer objects (DTOs) in Java, for example, by using the AsyncAPI Java generator. - These DTOs are used in the code to ensure type safety and to provide a clear understanding of the data structure. + - (Future Plans) The AsyncAPI document will be used to generate Java DTOs using the AsyncAPI Java generator, ensuring type safety and clear data structure understanding. versions: - '3.0.0' storage: | @@ -146,17 +210,18 @@ asyncapi: #More specific details about AsyncAPI itself and how is it used. This pipeline uses a bash script to read the updated configuration from the customer's repository. It then generates a new AsyncAPI document reflecting these changes. maintainers: | - No specific maintainers are assigned to the AsyncAPI document. The document is automatically generated by a pipeline. + Customers maintain this document automatically by maintaining their own topic configurations. audience: #Specify if AsyncAPI audience is internal or external or both. internal: true external: false extensions: | none documentation: | - Documentation is generated via AsyncAPI CLI and published to the wiki right after the AsyncAPI file is generated. + Documentation is generated via AsyncAPI CLI and published to the Azure DevOps wiki right after the AsyncAPI file is generated. bindings: | none tools: | + * [AsyncAPI CLI](https://github.com/asyncapi/cli) * [AsyncAPI Generator](https://github.com/asyncapi/generator): * [markdown-template](https://github.com/asyncapi/markdown-template). fullExample: resources/casestudies/hdi/asyncapi.yaml diff --git a/public/resources/casestudies/hdi/asyncapi.yaml b/public/resources/casestudies/hdi/asyncapi.yaml index 2037540565a7..02eca7539f04 100644 --- a/public/resources/casestudies/hdi/asyncapi.yaml +++ b/public/resources/casestudies/hdi/asyncapi.yaml @@ -16,136 +16,253 @@ servers: protocol: amqp description: Azure Service Bus namespace endpoint for box. channels: - helloworld-emea: + claimStatus-emea: servers: - $ref: '#/servers/box-emea' - address: https://namespace.servicebus.windows.net/topic/example/helloworld + address: https://namespace.servicebus.windows.net/topic/example/claimStatus messages: - helloworld: - name: helloworld-Message + claimStatus: + name: claimStatus-Message contentType: application/json payload: - $ref: '#/components/schemas/helloworld-topic-v1.json' - test-topic-emea: + $ref: '#/components/schemas/claimStatus-example.json' + claimDetails-emea: servers: - $ref: '#/servers/box-emea' - address: https://namespace.servicebus.windows.net/topic/example/test-topic + address: https://namespace.servicebus.windows.net/topic/example/claimDetails messages: - test-topic: - name: test-topic-Message + claimDetails: + name: claimDetails-Message contentType: application/json payload: - $ref: '#/components/schemas/test-topic-v1.json' - test-pipeline-emea: - servers: - - $ref: '#/servers/box-emea' - address: https://namespace.servicebus.windows.net/topic/example/test-pipeline - messages: - test-pipeline: - name: test-pipeline-Message - contentType: application/json - payload: - $ref: '#/components/schemas/test-topic-v1.json' - source1-emea: - servers: - - $ref: '#/servers/box-emea' - address: https://namespace.servicebus.windows.net/topic/example/source1 - messages: - source1: - name: source1-Message - contentType: application/json - payload: - $ref: '#/components/schemas/test-topic-v1.json' + $ref: '#/components/schemas/claimDetails-example.json' operations: - helloworld-emea: - action: send - channel: - $ref: '#/channels/helloworld-emea' - messages: - - $ref: '#/channels/helloworld-emea/messages/helloworld' - test-topic-emea: - action: send - channel: - $ref: '#/channels/test-topic-emea' - messages: - - $ref: '#/channels/test-topic-emea/messages/test-topic' - test-pipeline-emea: + claimStatus-emea: action: send channel: - $ref: '#/channels/test-pipeline-emea' + $ref: '#/channels/claimStatus-emea' messages: - - $ref: '#/channels/test-pipeline-emea/messages/test-pipeline' - source1-emea: + - $ref: '#/channels/claimStatus-emea/messages/claimStatus' + claimDetails-emea: action: send channel: - $ref: '#/channels/source1-emea' + $ref: '#/channels/claimDetails-emea' messages: - - $ref: '#/channels/source1-emea/messages/source1' + - $ref: '#/channels/claimDetails-emea/messages/claimDetails' components: schemas: - test-topic-v1.json: - $schema: http://json-schema.org/draft-06/schema# - type: object - properties: - eventType: - type: object - enum: - - create - - update - - delete - hotel: - type: object - properties: - id: - type: string - name: - type: string - slogan: - type: string - location: - type: string - total_number_of_rooms: - type: integer - currently_available_rooms: - type: integer - currently_occupied_rooms: - type: integer - required: - - id - - name - required: - - eventType - - hotel - helloworld-topic-v1.json: - $schema: http://json-schema.org/draft-06/schema# - type: object - properties: - eventType: - type: object - enum: - - create - - update - - delete - hotel: - type: object - properties: - id: - type: string - name: - type: string - slogan: - type: string - location: - type: string - total_number_of_rooms: - type: integer - currently_available_rooms: - type: integer - currently_occupied_rooms: - type: integer - required: - - id - - name - required: - - eventType - - hotel + claimDetails-example.json: { + "$schema": "http://json-schema.org/draft-06/schema#", + "type": "object", + "properties": { + "policyNumber": { + "type": "string" + }, + "claimNumber": { + "type": "string" + }, + "notificationDate": { + "type": "string" + }, + "occurrenceDate": { + "type": "string" + }, + "claimAmount": { + "type": "integer" + }, + "description": { + "type": "string" + }, + "editor": { + "type": "string" + }, + "location": { + "type": "string" + }, + "country": { + "type": "string" + }, + "currency": { + "type": "string" + }, + "movements": { + "type": "array", + "items": [ + { + "type": "object", + "properties": { + "amount": { + "type": "integer" + }, + "movementType": { + "type": "string" + }, + "benefitType": { + "type": "string" + } + }, + "required": [ + "amount", + "movementType", + "benefitType" + ] + }, + { + "type": "object", + "properties": { + "amount": { + "type": "integer" + }, + "movementType": { + "type": "string" + }, + "benefitType": { + "type": "string" + } + }, + "required": [ + "amount", + "movementType", + "benefitType" + ] + }, + { + "type": "object", + "properties": { + "amount": { + "type": "integer" + }, + "movementType": { + "type": "string" + }, + "benefitType": { + "type": "string" + } + }, + "required": [ + "amount", + "movementType", + "benefitType" + ] + } + ] + } + }, + "required": [ + "policyNumber", + "claimNumber" + ] +} + claimStatus-example.json: { + "$schema": "http://json-schema.org/draft-06/schema#", + "type": "object", + "properties": { + "message": { + "type": "object", + "properties": { + "version": { + "type": "string" + }, + "header": { + "type": "object", + "properties": { + "messageId": { + "type": "string" + }, + "entityType": { + "type": "string" + }, + "eventType": { + "type": "object", + "enum": [ + "create", + "update" + ] + } + }, + "required": [ + "messageId", + "entityType", + "eventType" + ] + }, + "data": { + "type": "object", + "properties": { + "par": { + "type": "object", + "properties": { + "tenantNumber": { + "type": "string" + }, + "policyNumber": { + "type": "number" + }, + "contractNumber": { + "type": "number" + }, + "sourceSystem": { + "type": "string" + }, + "claimStatus": { + "type": "string" + }, + "currencyCode": { + "type": "string" + }, + "registrYear": { + "type": "number" + }, + "broker": { + "type": "string" + }, + "insured": { + "type": "string" + }, + "lineOfBusiness": { + "type": "number" + }, + "claimCountry": { + "type": "string" + }, + "isNewClaim": { + "type": "boolean" + }, + "dateOfLoss": { + "type": "string", + "format": "date" + }, + "creationDate": { + "type": "string", + "format": "date" + }, + "notificationDate": { + "type": "string", + "format": "date" + }, + "businessDate": { + "type": "string", + "format": "date" + } + }, + "required": [ + "tenantNumber" + ] + } + }, + "required": [ + "par" + ] + } + }, + "required": [ + "version", + "header", + "data" + ] + } + }, + "required": [ + "message" + ] +} From ef006232052de15f451225b2d023ae01aa32af56 Mon Sep 17 00:00:00 2001 From: Lukasz Gornicki Date: Mon, 29 Jul 2024 13:35:54 +0200 Subject: [PATCH 14/14] Update hdi.yml --- config/casestudies/hdi.yml | 5 +++-- 1 file changed, 3 insertions(+), 2 deletions(-) diff --git a/config/casestudies/hdi.yml b/config/casestudies/hdi.yml index f4fdb42094c9..521f8aa90044 100644 --- a/config/casestudies/hdi.yml +++ b/config/casestudies/hdi.yml @@ -35,8 +35,7 @@ technical: #We need some more technical information related to case study. protocols: - AMQP brokers: Azure Service Bus - testing: | - The AsyncAPI document is validated using the AsyncAPI CLI to confirm that the document is correctly formatted and adheres to the AsyncAPI specification right after creation and befor being commited to the documentation repository. + testing: n/a architecture: | The following [enterprise integration patterns](https://www.enterpriseintegrationpatterns.com/patterns/messaging) are applied : - [Message Channel](https://www.enterpriseintegrationpatterns.com/patterns/messaging/MessageChannel.html) @@ -209,6 +208,8 @@ asyncapi: #More specific details about AsyncAPI itself and how is it used. If changes for any topic are applied by a customer, the documentation pipeline is triggered. This pipeline uses a bash script to read the updated configuration from the customer's repository. It then generates a new AsyncAPI document reflecting these changes. + + The AsyncAPI document is validated using the AsyncAPI CLI to confirm that the document is correctly formatted and adheres to the AsyncAPI specification right after creation and befor being commited to the documentation repository. maintainers: | Customers maintain this document automatically by maintaining their own topic configurations. audience: #Specify if AsyncAPI audience is internal or external or both.