From 268445e048dbc19b40e399d2e52cfc736b0c1e05 Mon Sep 17 00:00:00 2001 From: Matatjahu Date: Thu, 9 Feb 2023 10:23:54 +0100 Subject: [PATCH 01/10] feat: add models and methods for 3.0.0 support --- docs/v1.md | 63 +++++++++++++++++++++++++++++++++++++++++++++++++++++- 1 file changed, 62 insertions(+), 1 deletion(-) diff --git a/docs/v1.md b/docs/v1.md index b118380..7e1b513 100644 --- a/docs/v1.md +++ b/docs/v1.md @@ -39,8 +39,15 @@ - operations(): `Operations` - messages(): `Messages` - parameters(): `ChannelParameters` +- hasTitle(): `boolean` +- title(): `string` | `undefined` +- hasSummary(): `boolean` +- summary(): `string` | `undefined` - hasDescription(): `boolean` - description(): `string` | `undefined` +- hasExternalDocs(): `boolean` +- externalDocs(): `ExternalDocumention` | `undefined` +- tags(): `Tags` - bindings(): `Bindings` - extensions(): `Extensions` @@ -50,6 +57,7 @@ - filterBy(filter: `(channel: Channel) => boolean`): `Channel[]` - filterBySend(): `Channel[]` - filterByReceive(): `Channel[]` +- filterByTags(tags: `string[]`): `Channel[]` - get(id: `string`): `Channel` | `undefined` - has(id: `string`): `boolean` @@ -80,8 +88,12 @@ - serverVariables(): `ServerVariables` - operationTraits(): `OperationTraits` - messageTraits(): `MessageTraits` +- replies(): `OperationReplies` +- replyAddresses(): `OperationReplyAddresses` - correlationIds(): `CorrelationIds` - securitySchemes(): `SecuritySchemes` +- tags(): `Tags`; +- externalDocs(): `ExternalDocumentations`; - serverBindings(): `Map` - channelBindings(): `Map` - operationBindings(): `Map` @@ -122,6 +134,7 @@ - has(id: `string`): `boolean` ## ExternalDocumention +- id(): `string` | `undefined` - url(): `string` - hasDescription(): `boolean` - description(): `string` | `undefined` @@ -189,6 +202,7 @@ - filterBy(filter: `(message: Message) => boolean`): `Message[]` - filterBySend(): `Message[]` - filterByReceive(): `Message[]` +- filterByTags(tags: `string[]`): `Message[]` - get(id: `string`): `Message` | `undefined` - has(id: `string`): `boolean` @@ -267,6 +281,8 @@ - action(): `enum{'send', 'receive', 'publish', 'subscribe'}` - isSend(): `boolean` - isReceive(): `boolean` +- hasTitle(): `boolean` +- title(): `string` | `undefined` - hasSummary(): `boolean` - summary(): `string` | `undefined` - hasDescription(): `boolean` @@ -278,6 +294,7 @@ - servers(): `Servers` - channels(): `Channels` - messages(): `Messages` +- reply(): `OperationReply` | `undefined` - traits(): `OperationTraits` - bindings(): `Bindings` - extensions(): `Extensions` @@ -288,11 +305,43 @@ - filterBy(filter: `(operation: Operation) => boolean`): `Operation[]` - filterBySend(): `Operation[]` - filterByReceive(): `Operation[]` +- filterByTags(tags: `string[]`): `Operation[]` - get(id: `string`): `Operation` | `undefined` - has(id: `string`): `boolean` +## OperationReply +- id(): `string` | `undefined` +- hasAddress(): `boolean` +- address(): `OperationReplyAddress` | `undefined` +- hasChannel(): `boolean` +- channel(): `Channel` | `undefined` +- extensions(): `Extensions` + +## OperationReplies +- all(): `OperationReply[]` +- isEmpty(): `boolean` +- filterBy(filter: `(reply: OperationReply) => boolean`): `OperationReply[]` +- get(id: `string`): `OperationReply` | `undefined` +- has(id: `string`): `boolean` + +## OperationReplyAddress +- id(): `string` | `undefined` +- location(): `string` +- hasDescription(): `boolean` +- description(): `string` | `undefined` +- extensions(): `Extensions` + +## OperationReplyAddresses +- all(): `OperationReplyAddress[]` +- isEmpty(): `boolean` +- filterBy(filter: `(address: OperationReplyAddress) => boolean`): `OperationReplyAddress[]` +- get(id: `string`): `OperationReplyAddress` | `undefined` +- has(id: `string`): `boolean` + ## OperationTrait - id(): `string` +- hasTitle(): `boolean` +- title(): `string` | `undefined` - hasSummary(): `boolean` - summary(): `string` | `undefined` - hasDescription(): `boolean` @@ -398,6 +447,7 @@ - flows(): `OAuthFlows` | `undefined` - hasOpenIdConnectUrl(): `boolean` - openIdConnectUrl(): `string` | `undefined` +- scopes(): `string[]` | `undefined` - extensions(): `Extensions` # SecuritySchemes @@ -410,17 +460,26 @@ ## Server - id(): `string` - url(): `string` +- host(): `string` - protocol(): `string` +- hasPathname(): `boolean` +- pathname(): `string` | `undefined` - hasProtocolVersion(): `boolean` - protocolVersion(): `string` | `undefined` +- hasTitle(): `boolean` +- title(): `string` | `undefined` +- hasSummary(): `boolean` +- summary(): `string` | `undefined` - hasDescription(): `boolean` - description(): `string` | `undefined` - variables(): `ServerVariables` - security(): `SecurityRequirements[]` +- hasExternalDocs(): `boolean` +- externalDocs(): `ExternalDocumention` | `undefined` +- tags(): `Tags` - channels(): `Channels` - operations(): `Operations` - messages(): `Messages` -- tags(): `Tags` - bindings(): `Bindings` - extensions(): `Extensions` @@ -430,6 +489,7 @@ - filterBy(filter: `(server: Server) => boolean`): `Server[]` - filterBySend(): `Server[]` - filterByReceive(): `Server[]` +- filterByTags(tags: `string[]`): `Server[]` - get(id: `string`): `Server` | `undefined` - has(id: `string`): `boolean` @@ -452,6 +512,7 @@ - has(id: `string`): `boolean` ## Tag +- id(): `string` | `undefined` - name(): `string` - hasDescription(): `boolean` - description(): `string` | `undefined` From 7d90cb7ae2e251d1ecfaf6784b0a319a22aff24e Mon Sep 17 00:00:00 2001 From: Matatjahu Date: Thu, 9 Feb 2023 11:03:01 +0100 Subject: [PATCH 02/10] update Readme models --- README.md | 21 ++++++++++++++++++--- 1 file changed, 18 insertions(+), 3 deletions(-) diff --git a/README.md b/README.md index 5db8702..4f925cb 100644 --- a/README.md +++ b/README.md @@ -1,4 +1,5 @@ # parser-api + Global API definition for all AsyncAPI Parser implementations. The API follows an Intent-driven design approach based on user intents rather than technical mechanics. @@ -28,25 +29,39 @@ Each parser will therefore maintain its own compatibility matrix between which s ### Models These are the most important models in this API: + - **AsyncAPIDocument** is the root model. Most of the intents are here, so users don't need to navigate through the object hierarchy. - **Binding** is a mechanism to define protocol-specific information. - **Channel** describes a `topic`/`channel` a Message is transmitted over by some Operation. +- **ChannelParameter** represents a Channel Parameter for channel address template substitution. - **Components** holds a set of reusable objects for different aspects of the AsyncAPI specification. - **Contact** contains Contact information of the Application or Client API. - **CorrelationId** specifies an identifier at design time that can be used for message tracing and correlation. +- **Extension** represents the value of a single object extensions. +- **ExternalDocumention** contains external documentation source described by External Documentation. - **Info** contains defined information about the Application or Client API. - **License** contains License information of the Application or Client API. -- **Message** represents a message in your message-driven architecture. They can relate to Operations and Channels, but the relationship is not mandatory. +- **Message** represents a message in your message-driven architecture. They can relate to Operations and Channels, but the relationship is not mandatory. +- **MessageExample** defines sample payload and headers examples of the described Message. +- **MessageTrait** defines reusable Message parts. - **OAuthFlow** holds configuration details for a supported OAuth Flow. - **OAuthFlows** allows configuration of the supported OAuth Flows. - **Operation** describes an action performed by the Application or the Client. It links messages with channels. +- **OperationReply** describes the reply characteristic in a request-reply Operation. +- **OperationReplyAddress** defines the address for the Operation Reply. +- **OperationTrait** defines reusable Operation parts. - **Schema** is a superset of the [JSON Schema Specification Draft 07](https://json-schema.org/understanding-json-schema/basics.html). See https://www.asyncapi.com/docs/specifications/latest#schemaObject. -- **SecurityScheme** represents security specifications for servers. +- **SecurityRequirement** represents used Security Scheme as security mechanism for Server and Operation with possible scopes. +- **SecurityScheme** represents security specification for Server and Operation. - **Server** represents a Server in your message-driven architecture. Application or Client always wants to connect to some server. - **ServerVariable** represents a Server Variable for server URL template substitution. -- **Tag** contains metadata +- **Tag** contains metadata described by Tag. + +> **Note** +> Each model described has its corresponding collection model (except **AsyncAPIDocument**), such as **Servers**. ## Development + To avoid polluting the API with intents that have no clear use case or can be replaced by a call to another model, we have defined the following rule: Intents at the root model (`AsyncAPI`) **SHOULD** never return properties of other models but instead answer questions, return the model itself or a collection of models. From ed30d60695efde53dcbc9af1f653f092f4fdc797 Mon Sep 17 00:00:00 2001 From: Matatjahu Date: Thu, 9 Feb 2023 11:08:40 +0100 Subject: [PATCH 03/10] add extensions in Binding model --- docs/v1.md | 1 + 1 file changed, 1 insertion(+) diff --git a/docs/v1.md b/docs/v1.md index 7e1b513..52be882 100644 --- a/docs/v1.md +++ b/docs/v1.md @@ -23,6 +23,7 @@ - protocol(): `string` - version(): `string` - value(): `any` +- extensions(): `Extensions` ## Bindings - all(): `Binding[]` From 14dd46472c7bb120749fb0eb9ed9ab28bb770cf6 Mon Sep 17 00:00:00 2001 From: Matatjahu Date: Thu, 9 Feb 2023 11:14:31 +0100 Subject: [PATCH 04/10] fix types for OAuthFlow --- docs/v1.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/v1.md b/docs/v1.md index 52be882..b2171e4 100644 --- a/docs/v1.md +++ b/docs/v1.md @@ -257,9 +257,9 @@ - has(id: `string`): `boolean` ## OAuthFlow -- hasAuthorizationUrl(): `string` | `undefined` +- hasAuthorizationUrl(): `boolean` - authorizationUrl(): `string` | `undefined` -- hasTokenUrl(): `string` | `undefined` +- hasTokenUrl(): `boolean` - tokenUrl(): `string` | `undefined` - hasRefreshUrl(): `boolean` - refreshUrl(): `string` | `undefined` From b10f8bab97befd35f88880674b2938e812c73226 Mon Sep 17 00:00:00 2001 From: Matatjahu Date: Thu, 9 Feb 2023 11:47:37 +0100 Subject: [PATCH 05/10] update version --- docs/v1.md | 6 +++++- 1 file changed, 5 insertions(+), 1 deletion(-) diff --git a/docs/v1.md b/docs/v1.md index b2171e4..f1c9d5a 100644 --- a/docs/v1.md +++ b/docs/v1.md @@ -1,4 +1,4 @@ -# AsyncAPI Parser API v1.0.0-alpha.4 +# AsyncAPI Parser API v1.0.0-alpha.5 ## AsyncAPIDocument - version(): `string` @@ -282,6 +282,8 @@ - action(): `enum{'send', 'receive', 'publish', 'subscribe'}` - isSend(): `boolean` - isReceive(): `boolean` +- hasOperationId(): `boolean` +- operationId(): `string` | `undefined` - hasTitle(): `boolean` - title(): `string` | `undefined` - hasSummary(): `boolean` @@ -341,6 +343,8 @@ ## OperationTrait - id(): `string` +- hasOperationId(): `boolean` +- operationId(): `string` | `undefined` - hasTitle(): `boolean` - title(): `string` | `undefined` - hasSummary(): `boolean` From f836be7fc9f0351cb1d9ec7965cc8c2b9ec55e1c Mon Sep 17 00:00:00 2001 From: Sergio Moya <1083296+smoya@users.noreply.github.com> Date: Fri, 21 Jul 2023 15:14:02 +0200 Subject: [PATCH 06/10] support multi-format schemas + expose through originalSchemaFormat --- docs/v1.md | 6 ++++-- 1 file changed, 4 insertions(+), 2 deletions(-) diff --git a/docs/v1.md b/docs/v1.md index 67acc36..ce6244f 100644 --- a/docs/v1.md +++ b/docs/v1.md @@ -167,7 +167,6 @@ ## Message - id(): `string` -- schemaFormat(): `string` - hasMessageId(): `boolean` - messageId(): `string` | `undefined` - hasCorrelationId(): `boolean` @@ -225,7 +224,8 @@ ## MessageTrait - id(): `string` -- schemaFormat(): `string` +- hasSchemaFormat(): `boolean` +- schemaFormat(): `string` | `undefined` - hasMessageId(): `boolean` - messageId(): `string` | `undefined` - hasCorrelationId(): `boolean` @@ -411,6 +411,8 @@ - propertyNames(): `Schema` | `undefined` - readOnly(): `boolean` | `undefined` - required(): `string[]` | `undefined` +- schemaFormat(): `string` +- originalSchemaFormat(): `string` - then(): `Schema` | `undefined` - title(): `string` | `undefined` - type(): `string` | `string[]` | `undefined` From 1b9cbb5b65282fbd8d69f80dce04d0c2d6b1aa8f Mon Sep 17 00:00:00 2001 From: Sergio Moya <1083296+smoya@users.noreply.github.com> Date: Fri, 21 Jul 2023 15:14:42 +0200 Subject: [PATCH 07/10] remove scopes from SecurityScheme since it is in SecurityRequirement --- docs/v1.md | 1 - 1 file changed, 1 deletion(-) diff --git a/docs/v1.md b/docs/v1.md index ce6244f..9073cbd 100644 --- a/docs/v1.md +++ b/docs/v1.md @@ -454,7 +454,6 @@ - flows(): `OAuthFlows` | `undefined` - hasOpenIdConnectUrl(): `boolean` - openIdConnectUrl(): `string` | `undefined` -- scopes(): `string[]` | `undefined` - extensions(): `Extensions` # SecuritySchemes From dd2792a566c66f0876cfe5784ff674fe92602f29 Mon Sep 17 00:00:00 2001 From: Sergio Moya <1083296+smoya@users.noreply.github.com> Date: Mon, 24 Jul 2023 15:28:49 +0200 Subject: [PATCH 08/10] remove originalSchemaFormat --- docs/v1.md | 1 - 1 file changed, 1 deletion(-) diff --git a/docs/v1.md b/docs/v1.md index 9073cbd..5f29f67 100644 --- a/docs/v1.md +++ b/docs/v1.md @@ -412,7 +412,6 @@ - readOnly(): `boolean` | `undefined` - required(): `string[]` | `undefined` - schemaFormat(): `string` -- originalSchemaFormat(): `string` - then(): `Schema` | `undefined` - title(): `string` | `undefined` - type(): `string` | `string[]` | `undefined` From 77dce531d0f0dfcba0e7e81f725b74de5f923c6f Mon Sep 17 00:00:00 2001 From: Sergio Moya <1083296+smoya@users.noreply.github.com> Date: Wed, 26 Jul 2023 16:12:11 +0200 Subject: [PATCH 09/10] add back hasSchemaFormat + schemaFormat to message to reduce breaking change impact --- docs/v1.md | 2 ++ 1 file changed, 2 insertions(+) diff --git a/docs/v1.md b/docs/v1.md index 5f29f67..c2c44e4 100644 --- a/docs/v1.md +++ b/docs/v1.md @@ -167,6 +167,8 @@ ## Message - id(): `string` +- hasSchemaFormat(): `boolean` +- schemaFormat(): `string` | `undefined` - hasMessageId(): `boolean` - messageId(): `string` | `undefined` - hasCorrelationId(): `boolean` From dba54e58f9933e2575811e5a45413246c8b98a0e Mon Sep 17 00:00:00 2001 From: Sergio Moya <1083296+smoya@users.noreply.github.com> Date: Thu, 10 Aug 2023 15:19:38 +0200 Subject: [PATCH 10/10] add operationReply.messages() method --- docs/v1.md | 1 + 1 file changed, 1 insertion(+) diff --git a/docs/v1.md b/docs/v1.md index c2c44e4..a636b02 100644 --- a/docs/v1.md +++ b/docs/v1.md @@ -320,6 +320,7 @@ - address(): `OperationReplyAddress` | `undefined` - hasChannel(): `boolean` - channel(): `Channel` | `undefined` +- messages(): `Messages` - extensions(): `Extensions` ## OperationReplies