From 10137ed7326b609cde6843bfecc43a18e3a4a3f5 Mon Sep 17 00:00:00 2001 From: derberg Date: Thu, 9 Nov 2023 18:54:23 +0100 Subject: [PATCH 1/4] docs: re-add `Coming from OpenAPI` --- components/Asyncapi3Comparison.js | 6 +- components/OpenAPIComparisonV3.js | 221 ++++++++++++++++++ .../getting-started/coming-from-openapi.md | 31 +++ 3 files changed, 255 insertions(+), 3 deletions(-) create mode 100644 components/OpenAPIComparisonV3.js create mode 100644 pages/docs/tutorials/getting-started/coming-from-openapi.md 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..6a3f4ca750f --- /dev/null +++ b/components/OpenAPIComparisonV3.js @@ -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 ( +
+
+

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, Operation: true }))} onMouseLeave={() => setHoverState({ ...hoverState, Operation: false })}> + Operation (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 })}> + Message + +
+ Headers +
+
+ Payload +
+
+
+ + +
+
+
+
+
+
setHoverState(prevState => ({ ...prevState, Operation: true }))} onMouseLeave={() => setHoverState({ Operation: false })}> + Operations +
+
+ Operation + +
+
+ action (send or receive) +
+
+ channel reference +
+
+ 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..19b8f9685ee --- /dev/null +++ b/pages/docs/tutorials/getting-started/coming-from-openapi.md @@ -0,0 +1,31 @@ +--- +title: "Coming from OpenAPI and beyond" +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. + +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): + +import OpenAPIComparison from '../../../../components/OpenAPIComparison' + + + +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. + +import OpenAPIComparisonV3 from '../../../../components/OpenAPIComparisonV3' + + + +Aside from structural differences you must know that: + +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. +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. +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. + +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. From e520bcd1ce8ce2f3e9f3be352283e73ac4d3a35d Mon Sep 17 00:00:00 2001 From: Alejandra Quetzalli Date: Fri, 10 Nov 2023 16:34:38 -0800 Subject: [PATCH 2/4] tw editorial fixes --- .../getting-started/coming-from-openapi.md | 16 ++++++++-------- 1 file changed, 8 insertions(+), 8 deletions(-) diff --git a/pages/docs/tutorials/getting-started/coming-from-openapi.md b/pages/docs/tutorials/getting-started/coming-from-openapi.md index 19b8f9685ee..8555ace92e6 100644 --- a/pages/docs/tutorials/getting-started/coming-from-openapi.md +++ b/pages/docs/tutorials/getting-started/coming-from-openapi.md @@ -3,29 +3,29 @@ title: "Coming from OpenAPI and beyond" 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. +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. -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): +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' -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. +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 must know that: +Aside from structural differences, you should know: 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. -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. +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 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. +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. -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. +Let's learn how to create an AsyncAPI document that defines a "Hello world" application. From ce73394a0849877a2433b2e7dd1606d48d0ea7dc Mon Sep 17 00:00:00 2001 From: Alejandra Quetzalli Date: Fri, 10 Nov 2023 16:37:50 -0800 Subject: [PATCH 3/4] =?UTF-8?q?not=20a=20fancy=20blog=20post=20title=20?= =?UTF-8?q?=F0=9F=98=82?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- pages/docs/tutorials/getting-started/coming-from-openapi.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/pages/docs/tutorials/getting-started/coming-from-openapi.md b/pages/docs/tutorials/getting-started/coming-from-openapi.md index 8555ace92e6..ad7f6acb2cb 100644 --- a/pages/docs/tutorials/getting-started/coming-from-openapi.md +++ b/pages/docs/tutorials/getting-started/coming-from-openapi.md @@ -1,5 +1,5 @@ --- -title: "Coming from OpenAPI and beyond" +title: "Coming from OpenAPI" weight: 20 --- From 2786be6879b6a2e3624ccf5742bdb3c2afb1118d Mon Sep 17 00:00:00 2001 From: derberg Date: Mon, 13 Nov 2023 12:33:05 +0100 Subject: [PATCH 4/4] fix comparizon --- components/OpenAPIComparisonV3.js | 33 ++++++++++++++++++------------- 1 file changed, 19 insertions(+), 14 deletions(-) diff --git a/components/OpenAPIComparisonV3.js b/components/OpenAPIComparisonV3.js index 6a3f4ca750f..911776bbc75 100644 --- a/components/OpenAPIComparisonV3.js +++ b/components/OpenAPIComparisonV3.js @@ -7,7 +7,9 @@ export default function OpenAPIComparisonV3({ className = '' }) { Paths: false, PathItem: true, Summary: false, - Operation: false, + Operations: false, + OperationItem: true, + OperationType: false, Message: false, Tags: false, External: false, @@ -42,17 +44,19 @@ export default function OpenAPIComparisonV3({ className = '' }) { Summary and description
-
setHoverState(prevState => ({ ...prevState, Operation: true }))} onMouseLeave={() => setHoverState({ ...hoverState, Operation: false })}> - Operation (GET, PUT, POST, etc.) - -
+
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
-
+
@@ -125,7 +129,7 @@ export default function OpenAPIComparisonV3({ className = '' }) {
setHoverState(prevState => ({ ...prevState, Message: true }))} onMouseLeave={() => setHoverState({ Message: false })}> - Message + Messages
Headers @@ -142,21 +146,22 @@ export default function OpenAPIComparisonV3({ className = '' }) {
-
setHoverState(prevState => ({ ...prevState, Operation: true }))} onMouseLeave={() => setHoverState({ Operation: false })}> +
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)
-
- channel reference +
{ return setHoverState(prevState => ({ ...prevState, PathItem: true })) }} onMouseLeave={() => { return setHoverState({ ...hoverState, PathItem: false }) }}> + + Channel reference
-
- messages reference +
setHoverState(prevState => ({ ...prevState, Message: true }))} onMouseLeave={() => setHoverState({ ...hoverState, Message: false })}> + Messages reference