diff --git a/components/Asyncapi3Comparison.js b/components/Asyncapi3Comparison.js index c4e8800204b..e7c0773238a 100644 --- a/components/Asyncapi3Comparison.js +++ b/components/Asyncapi3Comparison.js @@ -120,7 +120,7 @@ export function Asyncapi3Comparison({ className = '' }) { Channels
setHoverState(prevState => ({ ...prevState, PathItem: true }))} onMouseLeave={() => setHoverState({ PathItem: false })}> - Channel Item + Channel
address @@ -229,7 +229,7 @@ export function Asyncapi3ChannelComparison({ className = '' }) { Channels
setHoverState(prevState => ({ ...prevState, PathItem: true }))} onMouseLeave={() => setHoverState({ PathItem: false })}> - Channel Item + Channel
setHoverState(prevState => ({ ...prevState, Message: true }))} onMouseLeave={() => setHoverState({ Message: false })}> Messages @@ -303,7 +303,7 @@ export function Asyncapi3IdAndAddressComparison({ className = '' }) { Channels
setHoverState(prevState => ({ ...prevState, PathItem: true }))} onMouseLeave={() => setHoverState({ PathItem: false })}> - Channel Item + Channel
diff --git a/components/OpenAPIComparisonV3.js b/components/OpenAPIComparisonV3.js new file mode 100644 index 00000000000..911776bbc75 --- /dev/null +++ b/components/OpenAPIComparisonV3.js @@ -0,0 +1,226 @@ +import React, { useState } from 'react'; + +export default function OpenAPIComparisonV3({ className = '' }) { + const [hoverState, setHoverState] = useState({ + Info: false, + Servers: false, + Paths: false, + PathItem: true, + Summary: false, + Operations: false, + OperationItem: true, + OperationType: false, + Message: false, + Tags: false, + External: false, + Components: false + }); + + return ( +
+
+

OpenAPI 3.0

+ +
+
setHoverState(prevState => ({ ...prevState, Info: true }))} onMouseLeave={() => setHoverState({ ...hoverState, Info: false })}> + Info +
+
+
setHoverState(prevState => ({ ...prevState, Servers: true }))} onMouseLeave={() => setHoverState({ ...hoverState, Servers: false })}> + Servers +
+
+ Security +
+
+
setHoverState(prevState => ({ ...prevState, Paths: true }))} onMouseLeave={() => setHoverState({ ...hoverState, Paths: false })}> + Paths +
+
{ return setHoverState(prevState => ({ ...prevState, PathItem: true })) }} onMouseLeave={() => { return setHoverState({ ...hoverState, PathItem: false }) }}> + Path Item + +
+
setHoverState(prevState => ({ ...prevState, Summary: true }))} onMouseLeave={() => { return setHoverState({ ...hoverState, Summary: false }) }}> + Summary and description +
+
+
setHoverState(prevState => ({ ...prevState, OperationItem: true }))} onMouseLeave={() => setHoverState({ ...hoverState, OperationItem: false })}> + Operation +
setHoverState(prevState => ({ ...prevState, OperationType: true }))} onMouseLeave={() => setHoverState({ ...hoverState, OperationType: false })}> + GET, PUT, POST, etc. +
+ +
setHoverState(prevState => ({ ...prevState, Message: true }))} onMouseLeave={() => setHoverState({ ...hoverState, Message: false })}> + Request +
+
setHoverState(prevState => ({ ...prevState, Message: true }))} onMouseLeave={() => setHoverState({ ...hoverState, Message: false })}> + Responses +
+ +
+
+
+
+
+
+
+
setHoverState(prevState => ({ ...prevState, Tags: true }))} onMouseLeave={() => setHoverState({ Tags: false })}> +

Tags

+
+
setHoverState(prevState => ({ ...prevState, External: true }))} onMouseLeave={() => setHoverState({ External: false })}> +

External Docs

+
+
+
setHoverState(prevState => ({ ...prevState, Components: true }))} onMouseLeave={() => setHoverState({ Components: false })}> + Components + +
+
+ Definitions +
+
+ Responses +
+
+ Parameters +
+
+ Response Headers +
+
+ Security Definitions +
+
+ Callbacks +
+
+ Links +
+
+
+
+
+ +
+

AsyncAPI 3.0

+ +
+
setHoverState(prevState => ({ ...prevState, Info: true }))} onMouseLeave={() => setHoverState({ Info: false })}> + Info +
+
+
setHoverState(prevState => ({ ...prevState, Servers: true }))} onMouseLeave={() => setHoverState({ Servers: false })}> + Servers (hosts + security) +
+
+
setHoverState(prevState => ({ ...prevState, Paths: true }))} onMouseLeave={() => setHoverState({ Paths: false })}> + Channels + +
+
setHoverState(prevState => ({ ...prevState, PathItem: true }))} onMouseLeave={() => setHoverState({ PathItem: false })}> + Channel + +
+
+
setHoverState(prevState => ({ ...prevState, Summary: true }))} onMouseLeave={() => setHoverState({ Summary: false })} > + Summary, description +
+ + +
+
setHoverState(prevState => ({ ...prevState, Message: true }))} onMouseLeave={() => setHoverState({ Message: false })}> + Messages + +
+ Headers +
+
+ Payload +
+
+
+ + +
+
+
+
+
+
setHoverState(prevState => ({ ...prevState, Operations: true }))} onMouseLeave={() => setHoverState({ Operations: false })}> + Operations +
+
setHoverState(prevState => ({ ...prevState, OperationItem: true }))} onMouseLeave={() => setHoverState({ OperationItem: false })}> + Operation + +
+
setHoverState(prevState => ({ ...prevState, OperationType: true }))} onMouseLeave={() => setHoverState({ OperationType: false })}> + action (send or receive) +
+
{ return setHoverState(prevState => ({ ...prevState, PathItem: true })) }} onMouseLeave={() => { return setHoverState({ ...hoverState, PathItem: false }) }}> + + Channel reference +
+
setHoverState(prevState => ({ ...prevState, Message: true }))} onMouseLeave={() => setHoverState({ ...hoverState, Message: false })}> + Messages reference +
+
+
+
+
+
+
+ Id (application identifier) +
+
+
+
setHoverState(prevState => ({ ...prevState, Tags: true }))} onMouseLeave={() => setHoverState({ Tags: false })}> +

Tags

+
+
setHoverState(prevState => ({ ...prevState, External: true }))} onMouseLeave={() => setHoverState({ External: false })}> +

External Docs

+
+
+
setHoverState(prevState => ({ ...prevState, Components: true }))} onMouseLeave={() => setHoverState({ Components: false })}> + Components + +
+
+ Schemas +
+
+ Messages +
+
+ Security Schemes +
+
+ Parameters +
+
+ Correlation Ids +
+
+ Operation Traits +
+
+ Message Traits +
+
+ Server Bindings +
+
+ Channel Bindings +
+
+ Operation Bindings +
+
+ Message Bindings +
+
+
+
+
+
+ ) +} diff --git a/pages/docs/tutorials/getting-started/coming-from-openapi.md b/pages/docs/tutorials/getting-started/coming-from-openapi.md new file mode 100644 index 00000000000..ad7f6acb2cb --- /dev/null +++ b/pages/docs/tutorials/getting-started/coming-from-openapi.md @@ -0,0 +1,31 @@ +--- +title: "Coming from OpenAPI" +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). AsyncAPI wanted to be as compatible as possible with OpenAPI so that users could reuse parts in both. + +Before AsyncAPI `3.0.0`, you could find many similarities between OpenAPI and AsyncAPI. Remember that in the world of event-driven architectures, you have more than one protocol; 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): + +import OpenAPIComparison from '../../../../components/OpenAPIComparison' + + + +To enable more flexibility, the AsyncAPI `3.0.0` specification changes more and is less similar to OpenAPI starting with this version. The biggest change is in the channel structure, where operations are separated from it. It is like detaching operations from paths in OpenAPI. + +import OpenAPIComparisonV3 from '../../../../components/OpenAPIComparisonV3' + + + +Aside from structural differences, you should know: + +1. AsyncAPI is compatible with OpenAPI schemas. +1. The message payload in AsyncAPI can be any value, not just an AsyncAPI/OpenAPI schema. For instance, it could be an Avro schema. +1. The [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 supports multiple protocols, not only HTTP, like in the case of OpenAPI. +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 specification's evolution 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. + +Let's learn how to create an AsyncAPI document that defines a "Hello world" application.