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.

Sign up for GitHub

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

Jump to bottom

docs: re-add Coming from OpenAPI #2307

Merged
merged 5 commits into from
Nov 14, 2023
Merged

docs: re-add Coming from OpenAPI #2307

Show file tree
Hide file tree
Changes from 1 commit
Commits
Show all changes
5 commits
Select commit Hold shift + click to select a range
10137ed
docs: re-add `Coming from OpenAPI`
derberg Nov 9, 2023
e520bcd
tw editorial fixes
quetzalliwrites Nov 11, 2023
ce73394
not a fancy blog post title 😂
quetzalliwrites Nov 11, 2023
2786be6
fix comparizon
derberg Nov 13, 2023
0ea2b42
Merge branch 'faffa' of https://github.com/derberg/website-asyncapi i…
derberg Nov 13, 2023
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
6 changes: 3 additions & 3 deletions components/Asyncapi3Comparison.js
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -120,7 +120,7 @@ export function Asyncapi3Comparison({ className = '' }) {
Channels

<div className={(hoverState.PathItem ? `bg-yellow-300` : 'bg-white') + ` border border-yellow-600 p-2 m-2`} onMouseOver={() => setHoverState(prevState => ({ ...prevState, PathItem: true }))} onMouseLeave={() => setHoverState({ PathItem: false })}>
Channel Item
Channel
<div className="flex flex-col flex-wrap flex-1">
<div className="border border-blue-500 bg-white hover:bg-blue-200 p-2 m-2">
address
Expand Down Expand Up @@ -229,7 +229,7 @@ export function Asyncapi3ChannelComparison({ className = '' }) {
Channels

<div className={(hoverState.PathItem ? `bg-yellow-300` : 'bg-white') + ` border border-yellow-600 p-2 m-2`} onMouseOver={() => setHoverState(prevState => ({ ...prevState, PathItem: true }))} onMouseLeave={() => setHoverState({ PathItem: false })}>
Channel Item
Channel
<div className="flex flex-col flex-wrap flex-1">
<div className={(hoverState.Message ? `bg-red-400` : 'bg-white') + ` flex-1 border border-red-600 p-2 m-2`} onMouseEnter={() => setHoverState(prevState => ({ ...prevState, Message: true }))} onMouseLeave={() => setHoverState({ Message: false })}>
Messages
Expand Down Expand Up @@ -303,7 +303,7 @@ export function Asyncapi3IdAndAddressComparison({ className = '' }) {
Channels

<div className={(hoverState.PathItem ? `bg-yellow-300` : 'bg-white') + ` border border-yellow-600 p-2 m-2`} onMouseOver={() => setHoverState(prevState => ({ ...prevState, PathItem: true }))} onMouseLeave={() => setHoverState({ PathItem: false })}>
Channel Item
Channel

<div className="flex flex-col flex-wrap flex-1">
<div className="border border-blue-500 bg-white hover:bg-blue-200 p-2 m-2">
Expand Down
221 changes: 221 additions & 0 deletions components/OpenAPIComparisonV3.js
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,221 @@
import React, { useState } from 'react';

export default function OpenAPIComparisonV3({ className = '' }) {
const [hoverState, setHoverState] = useState({
Info: false,
Servers: false,
Paths: false,
PathItem: true,
Summary: false,
Operation: false,
Message: false,
Tags: false,
External: false,
Components: false
});

return (
<div className={`${className} flex flex-wrap text-center`}>
<div className="flex-1 border border-black p-2 mr-1">
<h3 className="text-lg font-sans font-medium mb-4 ml-2">OpenAPI 3.0</h3>

<div>
<div className={(hoverState.Info ? `bg-blue-100 ` : ` `) + `border border-blue-300 p-2 m-2`} onMouseOver={() => setHoverState(prevState => ({ ...prevState, Info: true }))} onMouseLeave={() => setHoverState({ ...hoverState, Info: false })}>
Info
</div>
<div className="flex flex-wrap flex-1">
<div className={(hoverState.Servers ? `bg-green-100` : ' ') + ' flex-1 border border-green-300 p-2 m-2'} onMouseOver={() => setHoverState(prevState => ({ ...prevState, Servers: true }))} onMouseLeave={() => setHoverState({ ...hoverState, Servers: false })}>
Servers
</div>
<div className="flex-1 hover:bg-gray-200 border border-bg-gray-500 p-2 m-2">
Security
</div>
</div>
<div className={(hoverState.Paths ? `bg-yellow-100` : ' ') + ` border border-yellow-300 p-2 m-2`} onMouseEnter={() => setHoverState(prevState => ({ ...prevState, Paths: true }))} onMouseLeave={() => setHoverState({ ...hoverState, Paths: false })}>
Paths
<div className="flex flex-wrap flex-1">
<div className={(hoverState.PathItem ? `bg-yellow-300` : 'bg-white') + ` border border-yellow-600 p-2 m-2`} onMouseEnter={() => { return setHoverState(prevState => ({ ...prevState, PathItem: true })) }} onMouseLeave={() => { return setHoverState({ ...hoverState, PathItem: false }) }}>
Path Item

<div className="flex flex-col flex-wrap flex-1">
<div className={(hoverState.Summary ? 'bg-blue-200' : 'bg-white') + ` border border-blue-500 p-2 m-2`} onMouseEnter={() => setHoverState(prevState => ({ ...prevState, Summary: true }))} onMouseLeave={() => { return setHoverState({ ...hoverState, Summary: false }) }}>
Summary and description
</div>
<div className="flex flex-wrap flex-1">
<div className={(hoverState.Operation ? `bg-orange-100` : 'bg-white') + ` flex-1 border border-orange-300 p-2 m-2`} onMouseEnter={() => setHoverState(prevState => ({ ...prevState, Operation: true }))} onMouseLeave={() => setHoverState({ ...hoverState, Operation: false })}>
Operation (GET, PUT, POST, etc.)

<div className="flex flex-wrap flex-1">
<div className={(hoverState.Message ? `bg-red-400` : 'bg-white') + ` flex-1 border border-red-600 p-2 m-2`} onMouseEnter={() => setHoverState(prevState => ({ ...prevState, Message: true }))} onMouseLeave={() => setHoverState({ ...hoverState, Message: false })}>
Request
</div>
<div className={(hoverState.Message ? `bg-red-400` : 'bg-white') + ` flex-1 border border-red-600 p-2 m-2`} onMouseEnter={() => setHoverState(prevState => ({ ...prevState, Message: true }))} onMouseLeave={() => setHoverState({ ...hoverState, Message: false })}>
Responses
</div>
</div>
</div>
</div>
</div>
</div>
</div>
</div>
<div className="flex flex-wrap flex-1">
<div className={(hoverState.Tags ? `bg-pink-300` : ' ') + ` flex items-center justify-center flex-1 border border-black p-2 m-2`} onMouseOver={() => setHoverState(prevState => ({ ...prevState, Tags: true }))} onMouseLeave={() => setHoverState({ Tags: false })}>
<p>Tags</p>
</div>
<div className={(hoverState.External ? `bg-green-500` : ' ') + ` flex items-center justify-center flex-1 border border-black p-2 m-2`} onMouseOver={() => setHoverState(prevState => ({ ...prevState, External: true }))} onMouseLeave={() => setHoverState({ External: false })}>
<p>External Docs</p>
</div>
</div>
<div className={(hoverState.Components ? `bg-gray-100` : ' ') + ` flex-1 border border-black p-2 m-2`} onMouseOver={() => setHoverState(prevState => ({ ...prevState, Components: true }))} onMouseLeave={() => setHoverState({ Components: false })}>
Components

<div className="grid grid-cols-2 grid-gap-2 flex-1 mt-1">
<div className="bg-gray-100 border border-black p-2 m-2">
Definitions
</div>
<div className="bg-gray-100 border border-black p-2 m-2">
Responses
</div>
<div className="bg-gray-100 border border-black p-2 m-2">
Parameters
</div>
<div className="bg-gray-100 border border-black p-2 m-2">
Response Headers
</div>
<div className="bg-gray-100 border border-black p-2 m-2">
Security Definitions
</div>
<div className="bg-gray-100 border border-black p-2 m-2">
Callbacks
</div>
<div className="bg-gray-100 border border-black p-2 m-2">
Links
</div>
</div>
</div>
</div>
</div>

<div className="flex-1 border border-black p-2 ml-1">
<h3 className="text-lg font-sans font-medium mb-4 ml-2">AsyncAPI 3.0</h3>

<div>
<div className={(hoverState.Info ? `bg-blue-100 ` : ' ') + 'border border-blue-300 p-2 m-2'} onMouseOver={() => setHoverState(prevState => ({ ...prevState, Info: true }))} onMouseLeave={() => setHoverState({ Info: false })}>
Info
</div>
<div className="flex flex-wrap flex-1">
<div className={(hoverState.Servers ? `bg-green-100` : ' ') + ' flex-1 border border-green-300 p-2 m-2'} onMouseOver={() => setHoverState(prevState => ({ ...prevState, Servers: true }))} onMouseLeave={() => setHoverState({ Servers: false })}>
Servers (hosts + security)
</div>
</div>
<div className={(hoverState.Paths ? `bg-yellow-100` : ' ') + ` border border-yellow-300 p-2 m-2`} onMouseEnter={() => setHoverState(prevState => ({ ...prevState, Paths: true }))} onMouseLeave={() => setHoverState({ Paths: false })}>
Channels

<div className="flex flex-wrap flex-1">
<div className={(hoverState.PathItem ? `bg-yellow-300` : 'bg-white') + ` border border-yellow-600 p-2 m-2`} onMouseOver={() => setHoverState(prevState => ({ ...prevState, PathItem: true }))} onMouseLeave={() => setHoverState({ PathItem: false })}>
Channel

<div className="flex flex-wrap flex-1">
<div className="flex flex-wrap flex-1">
<div className={(hoverState.Summary ? 'bg-blue-200' : 'bg-white') + ` border border-blue-500 p-2 m-2`} onMouseOver={() => setHoverState(prevState => ({ ...prevState, Summary: true }))} onMouseLeave={() => setHoverState({ Summary: false })} >
Summary, description
</div>


<div className="flex flex-wrap flex-1">
<div className={(hoverState.Message ? `bg-red-400` : 'bg-white') + ` flex-1 border border-red-600 p-2 m-2`} onMouseEnter={() => setHoverState(prevState => ({ ...prevState, Message: true }))} onMouseLeave={() => setHoverState({ Message: false })}>
Message

<div className="flex-1 border border-black box-border mr-1 p-2 m-2">
Headers
</div>
<div className="flex-1 border border-black box-border mr-1 p-2 m-2">
Payload
</div>
</div>
</div>


</div>
</div>
</div>
</div>
</div>
<div className={(hoverState.Operation ? `bg-orange-100` : 'bg-white ') + ` flex-1 border border-orange-300 p-2 m-2`} onMouseOver={() => setHoverState(prevState => ({ ...prevState, Operation: true }))} onMouseLeave={() => setHoverState({ Operation: false })}>
Operations
<div className="flex flex-wrap flex-1">
<div className="flex-1 border border-orange-300 p-2 m-2">
Operation

<div className="flex flex-col flex-wrap flex-1">
<div className="border border-blue-500 bg-white hover:bg-blue-200 p-2 m-2">
action (send or receive)
</div>
<div className="border border-blue-500 bg-white hover:bg-blue-200 p-2 m-2">
channel reference
</div>
<div className="border border-blue-500 bg-white hover:bg-blue-200 p-2 m-2">
messages reference
</div>
</div>
</div>
</div>
</div>
<div className="flex flex-wrap flex-1">
<div className="flex-1 border border-black box-border hover:bg-blue-400 p-2 m-2">
Id (application identifier)
</div>
</div>
<div className="flex flex-wrap flex-1">
<div className={(hoverState.Tags ? `bg-pink-300` : ' ') + ` flex items-center justify-center flex-1 border border-black p-2 m-2`} onMouseOver={() => setHoverState(prevState => ({ ...prevState, Tags: true }))} onMouseLeave={() => setHoverState({ Tags: false })}>
<p>Tags</p>
</div>
<div className={(hoverState.External ? `bg-green-500` : ' ') + ` flex items-center justify-center flex-1 border border-black p-2 m-2`} onMouseOver={() => setHoverState(prevState => ({ ...prevState, External: true }))} onMouseLeave={() => setHoverState({ External: false })}>
<p>External Docs</p>
</div>
</div>
<div className={(hoverState.Components ? `bg-gray-100` : ' ') + ` flex-1 border border-black p-2 m-2`} onMouseOver={() => setHoverState(prevState => ({ ...prevState, Components: true }))} onMouseLeave={() => setHoverState({ Components: false })}>
Components

<div className="grid grid-cols-2 grid-gap-2 flex-wrap flex-1 mt-2">
<div className="bg-gray-100 border border-black box-border p-2 m-2">
Schemas
</div>
<div className="bg-gray-100 border border-black box-border p-2 m-2">
Messages
</div>
<div className="bg-gray-100 border border-black box-border p-2 m-2">
Security Schemes
</div>
<div className="bg-gray-100 border border-black box-border p-2 m-2">
Parameters
</div>
<div className="bg-gray-100 border border-black box-border p-2 m-2">
Correlation Ids
</div>
<div className="bg-gray-100 border border-black box-border p-2 m-2">
Operation Traits
</div>
<div className="bg-gray-100 border border-black box-border p-2 m-2">
Message Traits
</div>
<div className="bg-gray-100 border border-black box-border p-2 m-2">
Server Bindings
</div>
<div className="bg-gray-100 border border-black box-border p-2 m-2">
Channel Bindings
</div>
<div className="bg-gray-100 border border-black box-border p-2 m-2">
Operation Bindings
</div>
<div className="bg-gray-100 border border-black box-border p-2 m-2">
Message Bindings
</div>
</div>
</div>
</div>
</div>
</div >
)
}
31 changes: 31 additions & 0 deletions pages/docs/tutorials/getting-started/coming-from-openapi.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,31 @@
---
title: "Coming from OpenAPI and beyond"
quetzalliwrites marked this conversation as resolved.
Show resolved Hide resolved
weight: 20
---

If you're coming from OpenAPI, you must know that AsyncAPI [started as an adaptation of the OpenAPI specification](https://medium.com/asyncapi/whats-new-on-asyncapi-lots-2d9019a1869d). We wanted to have as much compatibility as possible between the two so users could reuse parts in both.
quetzalliwrites marked this conversation as resolved.
Show resolved Hide resolved

Prior AsyncAPI `3.0.0` you could find lots of similarities between OpenAPI and AsyncAPI. Just bear in mind that in the world of event-driven architectures, you have more than one protocol and therefore some things are different. Check out the following comparison chart, inspired by [Darrel Miller's blog post](https://www.openapis.org/news/blogs/2016/10/tdc-structural-improvements-explaining-30-spec-part-2):
quetzalliwrites marked this conversation as resolved.
Show resolved Hide resolved

import OpenAPIComparison from '../../../../components/OpenAPIComparison'

<OpenAPIComparison className="my-8" />

Starting with AsyncAPI `3.0.0` specification change more and is less similar to OpenAPI to enable more flexibility. You can notice the biggest change if the channel structure, where operation is separated from it. It is like you would detach operation from paths in OpenAPI.
quetzalliwrites marked this conversation as resolved.
Show resolved Hide resolved

import OpenAPIComparisonV3 from '../../../../components/OpenAPIComparisonV3'

<OpenAPIComparisonV3 className="my-8" />

Aside from structural differences you must know that:
quetzalliwrites marked this conversation as resolved.
Show resolved Hide resolved

1. AsyncAPI is compatible with OpenAPI schemas.
1. Message payload in AsyncAPI can be any value, not just an AsyncAPI/OpenAPI schema. For instance, it could be an Avro schema.
quetzalliwrites marked this conversation as resolved.
Show resolved Hide resolved
1. [AsyncAPI server object](/docs/specifications/2.2.0/#serverObject) is almost identical to its OpenAPI counterpart with the exception that `scheme` has been renamed to `protocol` and AsyncAPI introduces a new property called `protocolVersion`. AsyncAPI is there to support multiple different protocols, not only HTTP like in case of OpenAPI.
quetzalliwrites marked this conversation as resolved.
Show resolved Hide resolved
1. OpenAPI path parameters and [AsyncAPI channel parameters](/docs/specifications/2.2.0/#parameterObject) are a bit different since AsyncAPI doesn't have the notion of "query" and "cookie", and header parameters can be defined in the [message object](/docs/specifications/2.2.0/#messageObject). Therefore, AsyncAPI channel parameters are the equivalent of OpenAPI path parameters.

## Conclusion

As you have seen above, OpenAPI and AsyncAPI are similar but the evolution of the specification will bring more differences in the future. In a real-world environment, systems don't have just REST APIs or events but a mix of both. Most of the time, the information flowing in the events is very similar to the one the REST APIs have to handle in requests and responses; thus, being able to reuse schemas is a huge win.
quetzalliwrites marked this conversation as resolved.
Show resolved Hide resolved

Enough reading, it's time to get your hands dirty with some actual examples. Let's learn how to create an AsyncAPI document that defines a "Hello world" application.
quetzalliwrites marked this conversation as resolved.
Show resolved Hide resolved