Mirrors/api-guidelines
1
0
Fork 0
mirror of https://github.com/adidas/api-guidelines.git synced 2025-10-25 15:19:19 +00:00
Code Issues Packages Projects Releases Wiki Activity

FDP-5206 - Update guidelines and format

Browse Source
This commit is contained in:
Guillermo Lagunas
2025-06-10 16:01:34 +02:00
parent f4486b00b5
commit c587e3e014
15 changed files with 72 additions and 72 deletions
Download Patch File Download Diff File Expand all files Collapse all files

82
asynchronous-api-guidelines/kafka-asynchronous-guidelines/j_channels.md
View File

@@ -14,14 +14,14 @@ All AsyncAPI specs **MUST** include definitions for the channels (Kafka topics)
* External Docs
* Message details
In addition to those supported fields, it **MAY** be possible to use extension attributes (using the x- prefix) to specify specific configuration parameters and metadata. In so, the recommended attributes to use are :
In addition to those supported fields, it **MAY** be possible to use extension attributes (using the x- prefix) to specify specific configuration parameters and metadata. In so, the recommended attributes to use are:
* x-metadata
* To include additional configuration specific to your team or project
* x-configurations
* To include Kafka configuration parameters and producers/consumers
As the parameters can be different per environment, it is very convenient to add an additional level for the environment
As the parameters can be different per environment, it is very convenient to add an additional level for the environment.
As part of the publish/subscribe operations, the spec **SHOULD** specify the different Kafka clients currently consuming from the different topics for each cluster/environment. For this, the extended attributes x-producers and x-consumers will be used.
@@ -29,60 +29,60 @@ As part of the publish/subscribe operations, the spec **SHOULD** specify the dif
...
channels:
namespace.source.event.topic-name:
description: A description of the purpose of the topic and the contained information
servers: ["pivotalDev", "pivotalSit", "pivotalPro"]
description: 'A description of the purpose of the topic and the contained information'
servers: ['playground-dev', 'playground-sit', 'playground-pro']
x-metadata:
myField1: myValue1
myField2: myValue2
myField1: 'myValue1'
myField2: 'myValue2'
x-configurations:
pivotal.dev:
playground.dev:
kafka:
partitions: 12
replicas: 1
partitions: '12'
replicas: '1'
topicConfiguration:
min.insync.replicas: "1"
retention.ms: "2592000000"
pivotal.sit:
min.insync.replicas: '1'
retention.ms: '2592000000'
playground.sit:
kafka:
partitions: 12
replicas: 2
partitions: '12'
replicas: '2'
topicConfiguration:
min.insync.replicas: "1"
retention.ms: "2592000000"
min.insync.replicas: '1'
retention.ms: '2592000000'
    publish:
operationId: "producer"
summary: "Description for the operation"
description: "An extensive explanation about the operation"
operationId: 'producer'
summary: 'Description for the operation'
description: 'An extensive explanation about the operation'
security:
- producerAcl: []
tags:
- name: tagA
- name: tagB
- name: 'tagA'
- name: 'tagB'
x-producers:
pivotal.dev:
- producer1
- producer2
pivotal.sit:
- producer1
- producer2
pivotal.pro:
- producer3
- producer4
playground.dev:
- 'producer1'
- 'producer2'
playground.sit:
- 'producer1'
- 'producer2'
playground.pro:
- 'producer3'
- 'producer4'
externalDocs:
description: documentation
url: http://confluence.adidas.fdp/catalogue/myTopic
description: 'documentation'
url: 'http://confluence.adidas.fdp/catalogue/myTopic'
...
subscribe:
operationId: "consumer"
operationId: 'consumer'
...
x-consumers:
pivotal.dev:
- consumer1
- consumer2
pivotal.sit:
- consumer1
- consumer2
pivotal.pro:
- consumer3
playground.dev:
- 'consumer1'
- 'consumer2'
playground.sit:
- 'consumer1'
- 'consumer2'
playground.pro:
- 'consumer3'
...
```