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.

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

feat: add initial v3 converter support #180

Merged
merged 28 commits into from
Jul 24, 2023
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
28 commits
Select commit Hold shift + click to select a range
5072dae
feat: support AsyncAPI v3.0.0
magicmatatjahu Jan 28, 2023
421cbe2
support new ref mechanism for security
magicmatatjahu Jan 28, 2023
8bbadad
add tests for deep references
magicmatatjahu Feb 7, 2023
c69afc0
add more tests
magicmatatjahu Feb 7, 2023
1603a20
update readme
magicmatatjahu Feb 7, 2023
41ab9de
update readme
magicmatatjahu Feb 7, 2023
65292cb
update readme
magicmatatjahu Feb 7, 2023
d455f86
update readme
magicmatatjahu Feb 7, 2023
c5a0314
fix typo
magicmatatjahu Feb 7, 2023
7f0b221
nothing special
jonaslagoni Jun 13, 2023
e9b2080
Merge branch 'master' into add_v3_support
jonaslagoni Jun 21, 2023
b4d32a7
work in progress, use schema union
jonaslagoni Jun 22, 2023
6f28e9d
split out functionality
jonaslagoni Jun 22, 2023
af0384f
Merge branch 'master' into add_v3_support
jonaslagoni Jun 22, 2023
212ef95
remove unused file
jonaslagoni Jun 22, 2023
56bb330
fixed implementation
jonaslagoni Jun 22, 2023
9b7a241
Merge branch 'master' into add_v3_support
jonaslagoni Jun 22, 2023
d761c30
small change
jonaslagoni Jun 22, 2023
d555e08
add notice
jonaslagoni Jun 22, 2023
89f3e00
update readme
jonaslagoni Jun 22, 2023
06383c2
Update README.md
jonaslagoni Jun 26, 2023
d549e27
fix codesmell and readme
jonaslagoni Jun 27, 2023
d835211
refactor code
jonaslagoni Jun 27, 2023
aa367f8
fix tests
jonaslagoni Jun 27, 2023
03b00ef
fix code
jonaslagoni Jun 27, 2023
1627967
fix codesmell
jonaslagoni Jun 27, 2023
3ca480e
Merge branch 'master' into add_v3_support
derberg Jul 5, 2023
6e881ec
Merge branch 'master' into add_v3_support
magicmatatjahu Jul 20, 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
70 changes: 70 additions & 0 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -15,6 +15,7 @@ Convert [AsyncAPI](https://asyncapi.com) documents older to newer versions.
* [From CLI](#from-cli)
* [In JS](#in-js)
* [In TS](#in-ts)
- [Conversion 2.x.x to 3.x.x](#conversion-2xx-to-3xx)
- [Known missing features](#known-missing-features)
- [Development](#development)
- [Contribution](#contribution)
Expand Down Expand Up @@ -91,6 +92,75 @@ try {
}
```

## Conversion 2.x.x to 3.x.x

> **NOTE**: This feature is still WIP, and is until the final release of `3.0.0`.

Conversion to version `3.x.x` from `2.x.x` has several assumptions that should be know before converting:

- The input must be valid AsyncAPI document.
- External references are not resolved and converted, they remain untouched, even if they are incorrect.
- In version `3.0.0`, the channel identifier is no longer its address, but due to the difficulty of defining a unique identifier, we still treat the address as an identifier. If there is a need to assign an identifier other than an address, an `x-channelId` extension should be defined at the level of the given channel.

```yaml
# 2.x.x
channels:
users/signup:
x-channelId: 'userSignUp'
...
users/logout:
...

# 3.0.0
channels:
userSignUp:
...
users/logout:
...
```

- The `publish` operation is treated as a `receive` action, and `subscribe` is treated as a `send` action. Conversion by default is embraced from the application perspective. If you want to change this logic, you need to specify `v2tov3.pointOfView` configuration as `client`.
- If the operation does not have an `operationId` field defined, the unique identifier of the operation will be defined as a combination of the identifier of the channel on which the operation was defined + the type of operation, `publish` or `subscribe`. Identical situation is with messages. However, here the priority is the `messageId` field and then the concatenation `{publish|subscribe}.messages.{optional index of oneOf messages}`.

```yaml
# 2.x.x
channels:
users/signup:
publish:
message:
...
subscribe:
operationId: 'userSignUpEvent'
message:
oneOf:
- messageId: 'userSignUpEventMessage'
...
- ...


# 3.0.0
channels:
users/signup:
messages:
publish.message:
...
userSignUpEventMessage:
...
userSignUpEvent.message.1:
...
operations:
users/signup.publish:
action: receive
...
userSignUpEvent:
action: send
...
```

- Security requirements that use scopes are defined in the appropriate places inline, the rest as a reference to the `components.securitySchemes` objects.
- If servers are defined at the channel level, they are converted as references to the corresponding objects defined in the `servers` field.
- Channels and servers defined in components are also converted (unless configured otherwise).

## Known missing features

* When converting from 1.x to 2.x, Streaming APIs (those using `stream` instead of `topics` or `events`) are converted correctly but information about framing type and delimiter is missing until a [protocolInfo](https://github.com/asyncapi/extensions-catalog/issues/1) for that purpose is created.
Expand Down
4 changes: 3 additions & 1 deletion src/convert.ts
Original file line number Diff line number Diff line change
Expand Up @@ -2,6 +2,7 @@ import { dump } from 'js-yaml';

import { converters as firstConverters } from "./first-version";
import { converters as secondConverters } from "./second-version";
import { converters as thirdConverters } from "./third-version";

import { serializeInput } from "./utils";

Expand All @@ -12,7 +13,8 @@ import type { AsyncAPIDocument, ConvertVersion, ConvertOptions, ConvertFunction
*/
const converters: Record<string, ConvertFunction> = {
...firstConverters,
...secondConverters
...secondConverters,
...thirdConverters,
};
const conversionVersions = Object.keys(converters);

Expand Down
14 changes: 12 additions & 2 deletions src/interfaces.ts
Original file line number Diff line number Diff line change
Expand Up @@ -2,10 +2,20 @@
* PUBLIC TYPES
*/
export type AsyncAPIDocument = { asyncapi: string } & Record<string, any>;
export type ConvertVersion = '1.1.0' | '1.2.0' | '2.0.0-rc1' | '2.0.0-rc2' | '2.0.0' | '2.1.0' | '2.2.0' | '2.3.0' | '2.4.0' | '2.5.0' | '2.6.0';
export type ConvertOptions = { }
export type ConvertVersion = '1.1.0' | '1.2.0' | '2.0.0-rc1' | '2.0.0-rc2' | '2.0.0' | '2.1.0' | '2.2.0' | '2.3.0' | '2.4.0' | '2.5.0' | '2.6.0' | '3.0.0';
export type ConvertV2ToV3Options = {
idGenerator?: (data: { asyncapi: AsyncAPIDocument, kind: 'channel' | 'operation' | 'message', key: string | number | undefined, path: Array<string | number>, object: any, parentId?: string }) => string,
pointOfView?: 'application' | 'client',
useChannelIdExtension?: boolean;
convertServerComponents?: boolean;
convertChannelComponents?: boolean;
}
export type ConvertOptions = {
v2tov3?: ConvertV2ToV3Options;
}

/**
* PRIVATE TYPES
*/
export type ConvertFunction = (asyncapi: AsyncAPIDocument, options: ConvertOptions) => AsyncAPIDocument;

Loading