Skip to content

Commit

Permalink
feat!: release for version 3.0.0 of the spec (#759)
Browse files Browse the repository at this point in the history
Co-authored-by: Sergio Moya <[email protected]>
Co-authored-by: nickshoe <[email protected]>
Co-authored-by: Rishi <[email protected]>
Co-authored-by: Fran Méndez <[email protected]>
Co-authored-by: Heiko Henning <[email protected]>
Co-authored-by: Lukasz Gornicki <[email protected]>
Co-authored-by: samz <[email protected]>
Co-authored-by: Maciej Urbańczyk <[email protected]>
Co-authored-by: Vladimír Gorej <[email protected]>
  • Loading branch information
10 people authored Dec 5, 2023
1 parent 83fd0b9 commit d78dcea
Show file tree
Hide file tree
Showing 42 changed files with 5,476 additions and 2,090 deletions.
4 changes: 2 additions & 2 deletions .github/workflows/release.yml
Original file line number Diff line number Diff line change
Expand Up @@ -19,12 +19,12 @@ jobs:
with:
node-version: 18
- name: Add plugin for conventional commits
run: npm install --save-dev conventional-changelog-conventionalcommits@5.0.0
run: npm install --save-dev conventional-changelog-conventionalcommits@6.1.0
- name: Release to GitHub
env:
GITHUB_TOKEN: ${{ secrets.GH_TOKEN }}
GIT_AUTHOR_NAME: asyncapi-bot
GIT_AUTHOR_EMAIL: [email protected]
GIT_COMMITTER_NAME: asyncapi-bot
GIT_COMMITTER_EMAIL: [email protected]
run: npx semantic-release@17.4.3
run: npx semantic-release@21.0.7
12 changes: 11 additions & 1 deletion examples/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -2,4 +2,14 @@

In this directory, you can find some examples of AsyncAPI documents.

**Do you have an example that could be valuable?** Open a pull request to contribute it.
**Do you have an example that could be valuable?** Open a pull request to contribute it.

## File naming

You may notice `asyncapi` in the the name of each example. We recommend doing the same with your AsyncAPI document. This way you enable features like documentation display on node hover, auto completion and validation of your AsyncAPI documents in IDEs like VSCode or IntelliJ IDEA. IDEs integrate with [SchemaStore](https://www.schemastore.org/json/) where AsyncAPI specification JSON Schema files are referenced. Some IDEs do it by default, some, like VSCode require you to install additional extensions, like `YAML` extension.

## Editors

To edit your AsyncAPI documents, you can use [AsyncAPI Studio](https://studio.asyncapi.com/).

If you prefer to use your favourite IDE, there are official extensions for [VSCode](https://marketplace.visualstudio.com/items?itemName=asyncapi.asyncapi-preview) and [IntelliJ IDEA](https://plugins.jetbrains.com/plugin/15673-asyncapi)
333 changes: 333 additions & 0 deletions examples/adeo-kafka-request-reply-asyncapi.yml
Original file line number Diff line number Diff line change
@@ -0,0 +1,333 @@
asyncapi: 3.0.0
info:
title: Adeo AsyncAPI Case Study
version: "%REPLACED_BY_MAVEN%"
description: >
This Adeo specification illustrates how ADEO uses AsyncAPI to document some of their exchanges
contact:
name: AsyncAPI team
email: [email protected]
tags:
- name: costing
description: "Costing channels, used by Costing clients."
servers:
production:
host: "prod.url:9092"
protocol: kafka-secure
description: Kafka PRODUCTION cluster
security:
- $ref: '#/components/securitySchemes/sasl-ssl'
bindings:
kafka:
schemaRegistryUrl: >-
https://schema-registry.prod.url/
staging:
host: "staging.url:9092"
protocol: kafka-secure
description: Kafka STAGING cluster for `uat` and `preprod` environments
security:
- $ref: '#/components/securitySchemes/sasl-ssl'
bindings:
kafka:
schemaRegistryUrl: >-
https://schema-registry.staging.url/
dev:
host: "dev.url:9092"
protocol: kafka-secure
description: Kafka DEV cluster for `dev` and `sit` environments
security:
- $ref: '#/components/securitySchemes/sasl-ssl'
bindings:
kafka:
schemaRegistryUrl: >-
https://schema-registry.dev.url/
channels:
costingRequest:
address: "adeo-{env}-case-study-COSTING-REQUEST-{version}"
description: >
Use this topic to do a Costing Request to Costing product.
We use the
[**RecordNameStrategy**](https://docs.confluent.io/platform/current/schema-registry/serdes-develop/index.html#subject-name-strategy)
to infer the messages schema.
You have to define `x-value.subject.name.strategy` to
`io.confluent.kafka.serializers.subject.RecordNameStrategy` in your
producer to use the schema we manage.
The schema below illustrates how Costing Request messages are
handled.
![](https://user-images.githubusercontent.com/5501911/188920831-689cec5f-8dc3-460b-8794-0b54ec8b0ac8.png)
parameters:
env:
$ref: "#/components/parameters/Env"
version:
$ref: "#/components/parameters/Version"
bindings:
kafka:
replicas: 3
partitions: 3
topicConfiguration:
cleanup.policy: [ "delete" ]
retention.ms: 604800000
messages:
costingRequest:
$ref: "#/components/messages/costingRequestV1"





costingResponse:
address: "adeo-{env}-case-study-COSTING-RESPONSE-{version}"
description: >
This topic is used to REPLY Costing Requests and is targeted by the
`REPLY_TOPIC` header.
**You must grant PUBLISH access to our `svc-ccr-app` service account.**.
We use the
[**RecordNameStrategy**](https://docs.confluent.io/platform/current/schema-registry/serdes-develop/index.html#subject-name-strategy)
to infer the messages schema.
You have to define `key.subject.name.strategy` and
`x-value.subject.name.strategy` to
`io.confluent.kafka.serializers.subject.RecordNameStrategy` in your
consumer.
The schema below illustrates how Costing Response messages are
handled.
![](https://user-images.githubusercontent.com/5501911/188920831-689cec5f-8dc3-460b-8794-0b54ec8b0ac8.png)
parameters:
env:
$ref: "#/components/parameters/Env"
version:
$ref: "#/components/parameters/Version"
bindings:
kafka:
x-key.subject.name.strategy:
type: string
description: >
We use the RecordNameStrategy to infer the messages schema.
Use
`x-key.subject.name.strategy=io.confluent.kafka.serializers.subject.RecordNameStrategy`
in your consumer configuration.
x-value.subject.name.strategy:
type: string
description: >
We use the RecordNameStrategy to infer the messages schema.
Use
`x-value.subject.name.strategy=io.confluent.kafka.serializers.subject.RecordNameStrategy`
in your consumer configuration.
messages:
costingResponse:
$ref: "#/components/messages/costingResponse"




operations:
requestCosting:
action: receive
channel:
$ref: '#/channels/costingRequest'
reply:
channel:
$ref: '#/channels/costingResponse'
address:
location: '$message.header#/REPLY_TOPIC'
summary: |
[COSTING] Request one or more Costing calculation for any product
description: >
You can try a costing request using our [Conduktor producer
template](https://conduktor.url)
tags:
- name: costing
bindings:
kafka:
groupId:
type: string
description: >
The groupId must be prefixed by your `svc` account, deliver by the
Adeo Kafka team.
This `svc` must have the write access to the topic.
x-value.subject.name.strategy:
type: string
description: >
We use the RecordNameStrategy to infer the messages schema.
Use
`x-value.subject.name.strategy=io.confluent.kafka.serializers.subject.RecordNameStrategy`
in your producer configuration.
getCostingResponse:
action: send
channel:
$ref: '#/channels/costingResponse'
summary: >
[COSTING] Get the costing responses matching an initial Costing
Request.
bindings:
kafka:
groupId:
type: string
description: >
The groupId must be prefixed by your `svc` account, deliver by the
Adeo Kafka team.
This `svc` must have the read access to the topic.
tags:
- name: costing





components:
correlationIds:
costingCorrelationId:
description: >
This correlation ID is used for message tracing and messages
correlation.
This correlation ID is generated at runtime based on the `REQUEST_ID`
and sent to the RESPONSE message.
location: $message.header#/REQUEST_ID
messages:
costingRequestV1:
name: CostingRequestV1
title: Costing Request V1
summary: Costing Request V1 inputs.
tags:
- name: costing
correlationId:
$ref: "#/components/correlationIds/costingCorrelationId"
headers:
type: object
required:
- REQUESTER_ID
- REQUESTER_CODE
- REQUEST_ID
- REPLY_TOPIC
properties:
REQUEST_ID:
$ref: "#/components/schemas/RequestId"
REPLY_TOPIC:
$ref: "#/components/schemas/ReplyTopic"
REQUESTER_ID:
$ref: "#/components/schemas/RequesterId"
REQUESTER_CODE:
$ref: "#/components/schemas/RequesterCode"
payload:
schemaFormat: application/vnd.apache.avro;version=1.9.0
schema:
$ref: "https://www.asyncapi.com/resources/casestudies/adeo/CostingRequestPayload.avsc"
costingResponse:
name: CostingResponse
title: Costing Response
summary: Costing Response ouputs.
tags:
- name: costing
description: >
Please refer to the `CostingResponseKey.avsc` schema, available on [our
github
project](https://github.url/).
correlationId:
$ref: "#/components/correlationIds/costingCorrelationId"
headers:
type: object
properties:
CALCULATION_ID:
$ref: "#/components/schemas/MessageId"
CORRELATION_ID:
$ref: "#/components/schemas/CorrelationId"
REQUEST_TIMESTAMP:
type: string
format: date-time
description: Timestamp of the costing request
CALCULATION_TIMESTAMP:
type: string
format: date-time
description: Technical timestamp for the costing calculation
bindings:
kafka:
key:
$ref: "https://deploy-preview-921--asyncapi-website.netlify.app/resources/casestudies/adeo/CostingResponseKey.avsc"
payload:
schemaFormat: application/vnd.apache.avro;version=1.9.0
schema:
$ref: "https://deploy-preview-921--asyncapi-website.netlify.app/resources/casestudies/adeo/CostingResponsePayload.avsc"
schemas:
RequesterId:
type: string
description: The Costing requester service account used to produce costing request.
example: svc-ecollect-app
RequesterCode:
type: string
description: >-
The Costing requester code (generally the BU Code). The requester code
is useful to get the dedicated context (tenant).
example: 1
MessageId:
type: string
format: uuid
description: A unique Message ID.
example: 1fa6ef40-8f47-40a8-8cf6-f8607d0066ef
RequestId:
type: string
format: uuid
description: >-
A unique Request ID needed to define a `CORRELATION_ID` for exchanges,
which will be sent back in the Costing Responses.
example: 1fa6ef40-8f47-40a8-8cf6-f8607d0066ef
CorrelationId:
type: string
format: uuid
description: >-
A unique Correlation ID defined from the `REQUEST_ID` or the
`MESSAGE_ID` provided in the Costing Request.
example: 1fa6ef40-8f47-40a8-8cf6-f8607d0066ef
BuCode:
type: string
description: The Business Unit code for which data are applicable.
example: 1
ReplyTopic:
type: string
description: >
The Kafka topic where to send the Costing Response. This is required for
the [Return Address EIP
pattern](https://www.enterpriseintegrationpatterns.com/patterns/messaging/ReturnAddress.html).
**You must grant WRITE access to our `svc-ccr-app` service account.**
example: adeo-case-study-COSTING-RESPONSE-V1
ErrorStep:
type: string
description: |
The woker that has thrown the error.
example: EXPOSE_RESULT
ErrorMessage:
type: string
description: |
The error message describing the error.
example: Error message
ErrorCode:
type: string
description: |
The error code.
example: CURRENCY_NOT_FOUND
parameters:
Env:
description: Adeo Kafka Environement for messages publications.
enum:
- dev
- sit
- uat1
- preprod
- prod
Version:
description: the topic version you want to use
examples:
- V1
default: V1
securitySchemes:
sasl-ssl:
type: plain
x-sasl.jaas.config: >-
org.apache.kafka.common.security.plain.PlainLoginModule required
username="<CLUSTER_API_KEY>" password="<CLUSTER_API_SECRET>";
x-security.protocol: SASL_SSL
x-ssl.endpoint.identification.algorithm: https
x-sasl.mechanism: PLAIN
description: >
Use [SASL authentication with SSL
encryption](https://docs.confluent.io/platform/current/security/security_tutorial.html#configure-clients)
to connect to the ADEO Broker.
Loading

0 comments on commit d78dcea

Please sign in to comment.