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 models and methods for AsyncAPI 3.0.0 #86

Closed
Closed
21 changes: 18 additions & 3 deletions README.md
Original file line number Diff line number Diff line change
@@ -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.
Expand Down Expand Up @@ -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.
74 changes: 70 additions & 4 deletions docs/v1.md
Original file line number Diff line number Diff line change
@@ -1,4 +1,4 @@
# AsyncAPI Parser API v1.0.0-alpha.4
# AsyncAPI Parser API v1.0.0-alpha.5

## AsyncAPIDocument
- version(): `string`
Expand All @@ -23,6 +23,7 @@
- protocol(): `string`
- version(): `string`
- value(): `any`
- extensions(): `Extensions`

## Bindings
- all(): `Binding[]`
Expand All @@ -39,8 +40,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`

Expand All @@ -50,6 +58,7 @@
- filterBy(filter: `(channel: Channel) => boolean`): `Channel[]`
- filterBySend(): `Channel[]`
- filterByReceive(): `Channel[]`
- filterByTags(tags: `string[]`): `Channel[]`
- get(id: `string`): `Channel` | `undefined`
- has(id: `string`): `boolean`

Expand Down Expand Up @@ -80,8 +89,12 @@
- serverVariables(): `ServerVariables`
- operationTraits(): `OperationTraits`
- messageTraits(): `MessageTraits`
- replies(): `OperationReplies`
- replyAddresses(): `OperationReplyAddresses`
- correlationIds(): `CorrelationIds`
- securitySchemes(): `SecuritySchemes`
- tags(): `Tags`;
- externalDocs(): `ExternalDocumentations`;
- serverBindings(): `Map<string, Bindings>`
- channelBindings(): `Map<string, Bindings>`
- operationBindings(): `Map<string, Bindings>`
Expand Down Expand Up @@ -122,6 +135,7 @@
- has(id: `string`): `boolean`

## ExternalDocumention
- id(): `string` | `undefined`
- url(): `string`
- hasDescription(): `boolean`
- description(): `string` | `undefined`
Expand Down Expand Up @@ -189,6 +203,7 @@
- filterBy(filter: `(message: Message) => boolean`): `Message[]`
- filterBySend(): `Message[]`
- filterByReceive(): `Message[]`
- filterByTags(tags: `string[]`): `Message[]`
- get(id: `string`): `Message` | `undefined`
- has(id: `string`): `boolean`

Expand Down Expand Up @@ -242,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`
Expand All @@ -267,6 +282,10 @@
- action(): `enum{'send', 'receive', 'publish', 'subscribe'}`
- isSend(): `boolean`
- isReceive(): `boolean`
- hasOperationId(): `boolean`
- operationId(): `string` | `undefined`
- hasTitle(): `boolean`
- title(): `string` | `undefined`
- hasSummary(): `boolean`
- summary(): `string` | `undefined`
- hasDescription(): `boolean`
Expand All @@ -278,6 +297,7 @@
- servers(): `Servers`
- channels(): `Channels`
- messages(): `Messages`
- reply(): `OperationReply` | `undefined`
- traits(): `OperationTraits`
- bindings(): `Bindings`
- extensions(): `Extensions`
Expand All @@ -288,11 +308,45 @@
- 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`
smoya marked this conversation as resolved.
Show resolved Hide resolved

## 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`
- hasOperationId(): `boolean`
- operationId(): `string` | `undefined`
- hasTitle(): `boolean`
- title(): `string` | `undefined`
- hasSummary(): `boolean`
- summary(): `string` | `undefined`
- hasDescription(): `boolean`
Expand Down Expand Up @@ -398,6 +452,7 @@
- flows(): `OAuthFlows` | `undefined`
- hasOpenIdConnectUrl(): `boolean`
- openIdConnectUrl(): `string` | `undefined`
- scopes(): `string[]` | `undefined`
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This is already in SecurityRequirement

Copy link
Member

@smoya smoya Jul 21, 2023

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I'm removing this because it is already in the security requirement object, so afaik it is not really need here. I know this got simplified in v3 but still compatible. We don't need to mimic exactly what new versions do.

WDYT @derberg @fmvilas @jonaslagoni @magicmatatjahu

- extensions(): `Extensions`

# SecuritySchemes
Expand All @@ -410,17 +465,26 @@
## Server
- id(): `string`
- url(): `string`
smoya marked this conversation as resolved.
Show resolved Hide resolved
- 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`

Expand All @@ -430,6 +494,7 @@
- filterBy(filter: `(server: Server) => boolean`): `Server[]`
- filterBySend(): `Server[]`
- filterByReceive(): `Server[]`
- filterByTags(tags: `string[]`): `Server[]`
- get(id: `string`): `Server` | `undefined`
- has(id: `string`): `boolean`

Expand All @@ -452,6 +517,7 @@
- has(id: `string`): `boolean`

## Tag
- id(): `string` | `undefined`
smoya marked this conversation as resolved.
Show resolved Hide resolved
- name(): `string`
- hasDescription(): `boolean`
- description(): `string` | `undefined`
Expand Down