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

chore: add parameter section in migration #2293

Merged
merged 7 commits into from
Nov 29, 2023
Merged

chore: add parameter section in migration #2293

Show file tree
Hide file tree
Changes from 3 commits
Commits
Show all changes
7 commits
Select commit Hold shift + click to select a range
44ba2e0
add section and comparison
jonaslagoni Nov 6, 2023
47d65f6
small changes
jonaslagoni Nov 6, 2023
5d3a448
small changes
jonaslagoni Nov 6, 2023
6c84f1a
improvements
quetzalliwrites Nov 10, 2023
38534cd
tw editorial review
quetzalliwrites Nov 10, 2023
b52f7d8
add hooks for schema comparitor
jonaslagoni Nov 13, 2023
ad9be7a
Merge branch 'next-major-spec' into add_parameter_section
jonaslagoni Nov 17, 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
276 changes: 107 additions & 169 deletions components/Asyncapi3Comparison.js
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,174 +1,5 @@
import React, { useState } from 'react';

/**
* Main comparison that shows the full picture between v2 and v3
*/
export function Asyncapi3Comparison({ 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,
Id: false,
Path: false,
Host: false
});

return (
<div className={`${className} flex flex-col md:flex-row gap-1 flex-wrap text-center`}>
<div className="flex-1 border border-black p-2 ml-1">
<h3 className="text-lg font-sans font-medium mb-4 ml-2">AsyncAPI 2.x</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.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="border border-blue-300 p-2 m-2">
Servers
<div className="flex flex-col flex-wrap flex-1">
<div className="border border-blue-600 p-2 m-2">
Server
<div className="flex flex-wrap flex-1">
<div className={(hoverState.Host || hoverState.Path ? `bg-pink-300` : ' ') + ` flex items-center justify-center flex-1 border border-black p-2 m-2`} onMouseOver={() => setHoverState(prevState => ({ ...prevState, Host: true, Path: true }))} onMouseLeave={() => setHoverState({ Host: false, Path: false })}>
<p>Url</p>
</div>
</div>
</div>
</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 Item

<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`} onMouseOver={() => setHoverState(prevState => ({ ...prevState, Operation: true }))} onMouseLeave={() => setHoverState({ Operation: false })}>
Operation (Publish and Subscribe)

<div className="flex flex-col flex-wrap flex-1">
<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 })}>
Messages
<div className="flex-1 border border-black box-border mr-1 p-2 m-2">
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>
</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 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>
<div className="border border-blue-300 p-2 m-2">
Servers
<div className="flex flex-col flex-wrap flex-1">
<div className="border border-blue-600 p-2 m-2">
Server
<div className="flex flex-wrap flex-1">
<div className={(hoverState.Host ? `bg-pink-300` : ' ') + ` flex-1 border border-black box-border mr-1 p-2 m-2`} onMouseOver={() => setHoverState(prevState => ({ ...prevState, Host: true }))} onMouseLeave={() => setHoverState({ Host: false })}>
<p>Host</p>
</div>
<div className={(hoverState.Path ? `bg-pink-300` : ' ') + ` flex-1 border border-black box-border mr-1 p-2 m-2`} onMouseOver={() => setHoverState(prevState => ({ ...prevState, Path: true }))} onMouseLeave={() => setHoverState({ Path: false })}>
<p>Pathname</p>
</div>
</div>
</div>
</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={(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
<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
</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 })}>
Messages
<div className="flex-1 border border-black box-border mr-1 p-2 m-2">
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 className={(hoverState.Operation ? `bg-yellow-100` : ' ') + ` border border-yellow-300 p-2 m-2`} onMouseEnter={() => 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
</div>
<div className="border border-blue-500 bg-white hover:bg-blue-200 p-2 m-2">
messages
</div>
</div>
</div>
</div>
</div>
</div>
</div>
</div >
)
}

/**
* Used to compare how channels, operations and messages have changed
*/
Expand Down Expand Up @@ -560,3 +391,110 @@ export function Asyncapi3SchemaFormatComparison({ className = '' }) {
</div >
)
}

/**
* Compares how the parameter object changed location from v2 to v3
*/
export function Asyncapi3ParameterComparison({ className = '' }) {
const [hoverState, setHoverState] = useState({
location: false,
description: false,
enum: false,
examples: false,
default: false
});

return (
<div className={`${className} flex flex-col md:flex-row gap-1 flex-wrap text-center`}>
<div className="flex-1 border border-black p-2 ml-1">
<h3 className="text-lg font-sans font-medium mb-4 ml-2">AsyncAPI 2.x</h3>

<div>
<div className={'border border-yellow-300 p-2 m-2'}>
components | channels

<div className="flex flex-wrap flex-1">
<div className={'bg-white border border-yellow-600 p-2 m-2'}>
parameters

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

<div className="flex-1 bg-white border border-yellow-600 p-2 m-2">
schema
<div className="flex flex-wrap flex-1">
<div className={'bg-white flex-1 bg-red-300 p-2 m-2'}>type</div>
<div className={(hoverState.enum ? `bg-orange-300` : 'bg-white ') + ` flex-1 border border-orange-300 p-2 m-2`} onMouseOver={() => setHoverState(prevState => ({ ...prevState, enum: true }))} onMouseLeave={() => setHoverState({ enum: false })}>
enum
</div>
<div className={(hoverState.examples ? `bg-orange-300` : 'bg-white ') + ` flex-1 border border-orange-300 p-2 m-2`} onMouseOver={() => setHoverState(prevState => ({ ...prevState, examples: true }))} onMouseLeave={() => setHoverState({ examples: false })}>
examples
</div>
<div className={(hoverState.default ? `bg-orange-300` : 'bg-white ') + ` flex-1 border border-orange-300 p-2 m-2`} onMouseOver={() => setHoverState(prevState => ({ ...prevState, default: true }))} onMouseLeave={() => setHoverState({ default: false })}>
default
</div>
<div className={(hoverState.description ? `bg-orange-300` : 'bg-white ') + ` flex-1 border border-orange-300 p-2 m-2`} onMouseOver={() => setHoverState(prevState => ({ ...prevState, description: true }))} onMouseLeave={() => setHoverState({ description: false })}>
description
</div>
<div className={'bg-white flex-1 bg-red-300 p-2 m-2'}>pattern</div>
<div className={'bg-white flex-1 bg-red-300 p-2 m-2'}>multipleOf</div>
<div className={'bg-white flex-1 bg-red-300 p-2 m-2'}>And all other properties</div>
</div>
</div>
</div>
</div>
</div>
</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={'border border-yellow-300 p-2 m-2'}>
components | channels

<div className="flex flex-wrap flex-1">
<div className={'bg-white border border-yellow-600 p-2 m-2'}>
parameters

<div className="flex flex-wrap flex-1">
<div className={'bg-white border border-yellow-600 p-2 m-2'}>
parameter
<div className="flex flex-wrap flex-1">
<div className={(hoverState.location ? `bg-orange-300` : 'bg-white ') + ` flex-1 border border-orange-300 p-2 m-2`} onMouseOver={() => setHoverState(prevState => ({ ...prevState, location: true }))} onMouseLeave={() => setHoverState({ location: false })}>
location
</div>
<div className={(hoverState.description ? `bg-orange-300` : 'bg-white ') + ` flex-1 border border-orange-300 p-2 m-2`} onMouseOver={() => setHoverState(prevState => ({ ...prevState, description: true }))} onMouseLeave={() => setHoverState({ description: false })}>
description
</div>
<div className={(hoverState.enum ? `bg-orange-300` : 'bg-white ') + ` flex-1 border border-orange-300 p-2 m-2`} onMouseOver={() => setHoverState(prevState => ({ ...prevState, enum: true }))} onMouseLeave={() => setHoverState({ enum: false })}>
enum
</div>
<div className={(hoverState.examples ? `bg-orange-300` : 'bg-white ') + ` flex-1 border border-orange-300 p-2 m-2`} onMouseOver={() => setHoverState(prevState => ({ ...prevState, examples: true }))} onMouseLeave={() => setHoverState({ examples: false })}>
examples
</div>
<div className={(hoverState.default ? `bg-orange-300` : 'bg-white ') + ` flex-1 border border-orange-300 p-2 m-2`} onMouseOver={() => setHoverState(prevState => ({ ...prevState, default: true }))} onMouseLeave={() => setHoverState({ default: false })}>
default
</div>
</div>
</div>
</div>
</div>
</div>
</div>
</div>
</div>
</div >
)
}
58 changes: 53 additions & 5 deletions pages/docs/migration/migrating-to-v3.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,6 +1,9 @@
---
title: "Migrating to v3"
---



Migration to a new major version is always difficult, and AsyncAPI is no exception. To provide as smooth a transition as possible, this document shows the breaking changes between AsyncAPI v2 and v3 in an interactive manner.

If you want to update your AsyncAPI document, use the [AsyncAPI converter](https://github.com/asyncapi/converter-js) directly in the CLI with the following command:
Expand All @@ -11,9 +14,8 @@ asyncapi convert asyncapi.json --output=asyncapi_v3.json --target-version=3.0.0

For a detailed read-through about all the changes (non-breaking as well), read all the [v3 release notes](/blog/release-notes-3.0.0) first to acquire additional context about the changes introduced in v3.

import {Asyncapi3Comparison, Asyncapi3ChannelComparison, Asyncapi3IdAndAddressComparison, Asyncapi3MetaComparison, Asyncapi3OperationComparison,Asyncapi3SchemaFormatComparison, Asyncapi3ServerComparison} from '../../../components/Asyncapi3Comparison'

<Asyncapi3Comparison className="my-8" />
import {Asyncapi3ChannelComparison, Asyncapi3IdAndAddressComparison, Asyncapi3MetaComparison, Asyncapi3OperationComparison,Asyncapi3SchemaFormatComparison, Asyncapi3ServerComparison,
Asyncapi3ParameterComparison} from '../../../components/Asyncapi3Comparison'

## Moved metadata

Expand Down Expand Up @@ -203,14 +205,17 @@ channels:
user/signedup:
message:
oneOf:
- ...
- ...
- messageId: UserMessage
...
- messageId: UserMessage2
...

asyncapi: 2.6.0
...
channels:
user/signedup:
message:
messageId: UserMessage
...
```

Expand All @@ -236,6 +241,8 @@ channels:
...
```

This also means that we have removed the property `messageId` from the Message Object, as the ID of the Message Object is now the key in the key/value pair.

## Unifying explicit and implicit references

In v2, implicit references were allowed in certain instances. For instance, the server security configuration was identified by name, linking to a [Security Schema Object](https://www.asyncapi.com/docs/reference/specification/v2.6.0#securitySchemeObject) within the components. Similarly, a channel could reference global servers by name.
Expand Down Expand Up @@ -393,3 +400,44 @@ channels: {}
asyncapi: 3.0.0
...
```

## Restricted parameters object

Parameters has always been one that did not reflect the use-cases of the real world for the sacrifice of convenience.
quetzalliwrites marked this conversation as resolved.
Show resolved Hide resolved

<Asyncapi3ParameterComparison className="my-8" />

In v2, you had the full capability of the Schema Object, however it provides too many options that are rarely used. On-top of that, how are you ever going to serialize an object or boolean in the channel path?

In v2, we have simplified it significantly, so by constantly being of string type, and only giving a limited number of properties to use. Now you only have access to `enum`, `default`, `description`, `examples`, and `location`.
quetzalliwrites marked this conversation as resolved.
Show resolved Hide resolved

```yml
asyncapi: 2.6.0
...
channels:
user/{user_id}/signedup:
parameters:
location: "$message.payload"
description: Just a test description
schema:
type: string
enum: ["test"]
default: "test"
examples: ["test"]
...
```

```yml
asyncapi: 3.0.0
...
channels:
userSignedUp:
address: user/{user_id}/signedup
parameters:
user_id:
enum: ["test"]
default: "test"
description: Just a test description
examples: ["test"]
location: "$message.payload"
```