[📑 Docs]: cover AsyncAPI document sections in detail

[quetzalliwrites]

What Dev Docs changes are you proposing?

As part of Google Season of Docs 2023 at AsyncAPI, we're going to write in-depth explanations of the different sections of an AsyncAPI document to avoid difficulties in implementing EDAs.

Here are the individual sections of an AsyncAPI document we need to cover:

• AsyncAPI structure - Introduce all root elements, add short explanation of info, servers, channels, components, and their purpose.
• Adding variables to URL - Explain how to add variables to the server URL when parts of the URL may be different per runtime. Explain how these can be reused between two servers via components.serverVariables.
• Adding channel - Explain the purpose of channels, different names for it, and what users should put here. Add a simple channel there, and explain how it relates to the server. If you specify a channel and server, it is expected that a given channel is present on all servers. Explain that the channel can also specify that it is present only on server A or server B.
• Specifying dynamic parts of channel name - Explain how to use and reuse parameters.
• Adding operations - Introduce operations, how many there can be, what kind of, and their purpose, and explain pub/sub.
• Securing operations - Explain that server security applies to all the operations in all channels. Still, if you have different security per operation, you can use the security prop at the operation level.
• Adding messages - Add a simple message as in previous examples, explain the most important parts, and explain there can be one or multiple (oneOf) under operation. Talk about contentType and add a note about defaultSchema. Also, show how to reuse components.
• Payload schema - More complex message example with payload added using JSON and Avro schemas, and explain how to specify them. Explain how to reuse schema from components.
• AsyncAPI reusable parts - Explain the $ref concept, introduce and explain that $ref can point to the same document, other documents in a local system, and external URLs.
• Reuse with traits - Explain how trait concepts work.
• Organizing document with tags - Explain different tags info in different parts of AsyncAPI and their purpose.
• Extending AsyncAPI specification - Explain what to do when the specification does not yet support something you need, some field is missing, and more.
• Adding bindings - Add protocol-specific, additional info to AsyncAPI docs in different parts of the document, like server, channel, or message, to specify common things only for the given protocol.
• Adding servers - Add information about where to connect and what server to interact with the app.
• Adding servers' security - Add server security details.
• Adding reply info - Add info about a reply to a message, explain when one is when the reply is known and hard coded in the spec, but can be dynamic.

Tasks to complete in this epic

We'll break up the work into the following digestible pieces:

• Introduce AsyncAPI Document [📑 Docs]: introduce AsyncAPI document #1848
• AsyncAPI structure [📑 Docs]: document AsyncAPI structure  #1508
• Adding variables to URL [📑 Docs]: document adding variables to URL #1509
• Adding channel [📑 Docs]: document adding channel #1510
• Specifying dynamic parts of channel name [📑 Docs]: document specifying dynamic parts of channel name #1511
• Adding operations [📑 Docs]: document adding operations #1512
• Securing operations [📑 Docs]: document securing operations #1513
• Adding messages [📑 Docs]: document adding messages #1514
• Payload schema [📑 Docs]: document payload schema #1515
• AsyncAPI reusable parts [📑 Docs]: document AsyncAPI reusable parts #1516
• Reuse with traits [📑 Docs]: document how to reuse traits #1517
• Organizing document with tags [📑 Docs]: document organizing an AsyncAPI document with tags #1518
• Extending AsyncAPI specification [📑 Docs]: document extending the AsyncAPI specification #1519
• Adding bindings docs: document adding bindings #1713
• Adding servers docs: document adding servers #1714
• Adding servers' security docs: document adding servers' security #1715
• Adding reply info docs: document adding reply info #1716

Code of Conduct

• I agree to follow this project's Code of Conduct

[CatherineKiiru]

Hi @alequetzalli is this an active project? I'd like to work on it

[quetzalliwrites]

@CatherineKiiru Nope, this is a GSoD project which means only our GSoD writers can work on this. You can work on regular docs issues tho :)

[derberg]

Some missing stuff:

• Adding bindings - in asyncapi you can add a protocol-specific, additional info to AsyncAPI docs in different parts of the document, like server, or channel or message, to specify thing that are common only for given protocol.
• Adding servers - adding information about where to connect, to what server to interact with the ap
• Adding servers security - adding security details for a server
• Adding reply info - adding info about reply to a message, explain 2 concepts that one is when reply is known and hardcoded in spec, but can be dynamic

[smoya]

I suggest we clarify in the description of this issue that those docs should be based on AsyncAPI Spec version 3.

[TRohit20]

@alequetzalli as all the tasks pertaining to the EPIC issue in context are resolved, I deem the issue is now completely resolved, hence, closing the EPIC issue.