diff --git a/README.md b/README.md index f084330..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,6 +29,7 @@ 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. @@ -39,15 +41,18 @@ These are the most important models in this API: - **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 described by Tag. @@ -56,6 +61,7 @@ These are the most important models in this API: > 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. diff --git a/docs/v1.md b/docs/v1.md index 7f07eeb..a636b02 100644 --- a/docs/v1.md +++ b/docs/v1.md @@ -1,4 +1,4 @@ -# AsyncAPI Parser API v1.0.0 +# AsyncAPI Parser API v2.0.0 ## AsyncAPIDocument - version(): `string` @@ -40,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` @@ -51,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` @@ -81,8 +89,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` @@ -123,6 +135,7 @@ - has(id: `string`): `boolean` ## ExternalDocumention +- id(): `string` | `undefined` - url(): `string` - hasDescription(): `boolean` - description(): `string` | `undefined` @@ -154,7 +167,8 @@ ## Message - id(): `string` -- schemaFormat(): `string` +- hasSchemaFormat(): `boolean` +- schemaFormat(): `string` | `undefined` - hasMessageId(): `boolean` - messageId(): `string` | `undefined` - hasCorrelationId(): `boolean` @@ -190,6 +204,7 @@ - filterBy(filter: `(message: Message) => boolean`): `Message[]` - filterBySend(): `Message[]` - filterByReceive(): `Message[]` +- filterByTags(tags: `string[]`): `Message[]` - get(id: `string`): `Message` | `undefined` - has(id: `string`): `boolean` @@ -211,7 +226,8 @@ ## MessageTrait - id(): `string` -- schemaFormat(): `string` +- hasSchemaFormat(): `boolean` +- schemaFormat(): `string` | `undefined` - hasMessageId(): `boolean` - messageId(): `string` | `undefined` - hasCorrelationId(): `boolean` @@ -270,6 +286,8 @@ - isReceive(): `boolean` - hasOperationId(): `boolean` - operationId(): `string` | `undefined` +- hasTitle(): `boolean` +- title(): `string` | `undefined` - hasSummary(): `boolean` - summary(): `string` | `undefined` - hasDescription(): `boolean` @@ -281,6 +299,7 @@ - servers(): `Servers` - channels(): `Channels` - messages(): `Messages` +- reply(): `OperationReply` | `undefined` - traits(): `OperationTraits` - bindings(): `Bindings` - extensions(): `Extensions` @@ -291,13 +310,46 @@ - 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` +- messages(): `Messages` +- 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` - hasOperationId(): `boolean` - operationId(): `string` | `undefined` +- hasTitle(): `boolean` +- title(): `string` | `undefined` - hasSummary(): `boolean` - summary(): `string` | `undefined` - hasDescription(): `boolean` @@ -362,6 +414,7 @@ - propertyNames(): `Schema` | `undefined` - readOnly(): `boolean` | `undefined` - required(): `string[]` | `undefined` +- schemaFormat(): `string` - then(): `Schema` | `undefined` - title(): `string` | `undefined` - type(): `string` | `string[]` | `undefined` @@ -415,17 +468,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` @@ -435,6 +497,7 @@ - filterBy(filter: `(server: Server) => boolean`): `Server[]` - filterBySend(): `Server[]` - filterByReceive(): `Server[]` +- filterByTags(tags: `string[]`): `Server[]` - get(id: `string`): `Server` | `undefined` - has(id: `string`): `boolean` @@ -457,6 +520,7 @@ - has(id: `string`): `boolean` ## Tag +- id(): `string` | `undefined` - name(): `string` - hasDescription(): `boolean` - description(): `string` | `undefined`