Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

docs: introduce AsyncAPI document #1868

Merged
merged 18 commits into from
Dec 12, 2023
Merged
Show file tree
Hide file tree
Changes from 14 commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
4 changes: 4 additions & 0 deletions pages/docs/concepts/asyncapi-document/_section.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,4 @@
---
title: 'AsyncAPI Document'
weight: 50
---
44 changes: 44 additions & 0 deletions pages/docs/concepts/asyncapi-document/index.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,44 @@
---
title: 'Introduction'
weight: 50
---

quetzalliwrites marked this conversation as resolved.
Show resolved Hide resolved
The AsyncAPI Specification defines a set of files (AsyncAPI documents) required to describe the API of an application. The AsyncAPI document describes the message-driven API in accordance with the AsyncAPI Specification via JSON objects that conform to the JSON standards. (YAML, being a superset of JSON, can also be used.) It also offers a standardized approach for documenting and describing asynchronous and event-driven systems, clearly defining various components like channels and messages. Additionally, users can leverage both the AsyncAPI document and tools like the AsyncAPI Generator for code and documentation generation, enhancing efficiency and consistency in their development processes.
quetzalliwrites marked this conversation as resolved.
Show resolved Hide resolved
quetzalliwrites marked this conversation as resolved.
Show resolved Hide resolved

Furthermore, the AsyncAPI document acts as a communication contract between `receivers` and `senders` within an event-driven system. It specifies the payload content required when a service produces a message and offers clear guidance to the receiver regarding the message's properties.
quetzalliwrites marked this conversation as resolved.
Show resolved Hide resolved

```YAML
asyncapi: 3.0.0
info:
title: Cool Example
version: 0.1.0
channels:
userSignedUp:
address: user/signedup
messages:
userSignedUp:
description: An event describing that a user just signed up.
payload:
type: object
additionalProperties: false
quetzalliwrites marked this conversation as resolved.
Show resolved Hide resolved
properties:
fullName:
type: string
email:
type: string
format: email
age:
type: integer
minimum: 18
operations:
userSignedUp:
action: send
channel:
$ref: '#/channels/userSignedUp'
quetzalliwrites marked this conversation as resolved.
Show resolved Hide resolved
```

<Remember>
You might have additional fields depending on the implemented protocol (i.e., MQTT, AMQP, Kafka, etc.).

For example, your AsyncAPI document could have additional fields for <a href= "https://github.com/asyncapi/bindings/tree/master/kafka">configuring Kafka bindings</a>.
</Remember>