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 9 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
---
42 changes: 42 additions & 0 deletions pages/docs/concepts/asyncapi-document/index.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,42 @@
---
title: 'Introduction'
weight: 50
---

quetzalliwrites marked this conversation as resolved.
Show resolved Hide resolved
The AsyncAPI Specification defines a set of files required to describe the API of an application. One of those files is the AsyncAPI document; it 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.) The AsyncAPI document 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.
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

One of those files is the AsyncAPI document

I don't think we have other kind of files rather than the AsyncAPI document.

Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

ah, noted! fixing

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.).
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I would clarify this with an example

Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Thank you, noted. Added an example, you let me know if you like it.

quetzalliwrites marked this conversation as resolved.
Show resolved Hide resolved
</Remember>
Loading