feat: add new channels object #827
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
|
|
@@ -56,7 +56,7 @@ It means that the [application](#definitionsApplication) allows [consumers](#def | |
| - [Server Variable Object](#serverVariableObject) | ||
| - [Default Content Type](#defaultContentTypeString) | ||
| - [Channels Object](#channelsObject) | ||
| - [Channel Object](#channelObject) | ||
| - [Operation Object](#operationObject) | ||
| - [Operation Trait Object](#operationTraitObject) | ||
| - [Message Object](#messageObject) | ||
|
|
@@ -162,7 +162,7 @@ Field Name | Type | Description | |
| <a name="A2SInfo"></a>info | [Info Object](#infoObject) | **Required.** Provides metadata about the API. The metadata can be used by the clients if needed. | ||
| <a name="A2SServers"></a>servers | [Servers Object](#serversObject) | Provides connection details of servers. | ||
| <a name="A2SDefaultContentType"></a>defaultContentType | [Default Content Type](#defaultContentTypeString) | Default content type to use when encoding/decoding a message's payload. | ||
| <a name="A2SChannels"></a>channels | [Channels Object](#channelsObject) | The channels used by this [application](#definitionsApplication). | ||
| <a name="A2SComponents"></a>components | [Components Object](#componentsObject) | An element to hold various reusable objects for the specification. Everything that is defined inside this object represents a resource that MAY or MAY NOT be used in the rest of the document and MAY or MAY NOT be used by the implemented [Application](#definitionsApplication). | ||
| <a name="A2STags"></a>tags | [Tags Object](#tagsObject) | A list of tags used by the specification with additional metadata. Each tag name in the list MUST be unique. | ||
| <a name="A2SExternalDocs"></a>externalDocs | [External Documentation Object](#externalDocumentationObject) | Additional external documentation. | ||
|
|
@@ -529,23 +529,22 @@ defaultContentType: application/json | |
|
|
||
| #### <a name="channelsObject"></a>Channels Object | ||
|
|
||
| An object containing all the [Channel Object](#channelObject) definitions the [Application](#definitionsApplication) MUST use during runtime. | ||
|
|
||
| ##### Patterned Fields | ||
|
|
||
| Field Pattern | Type | Description | ||
| ---|:---:|--- | ||
| <a name="channelsObjectChannel"></a>{channelId} | [Channel Object](#channelObject) \| [Reference Object](#referenceObject) | An identifier for the described channel. The `channelId` value is **case-sensitive**. Tools and libraries MAY use the `channelId` to uniquely identify a channel, therefore, it is RECOMMENDED to follow common programming naming conventions. | ||
|
|
||
| ##### Channels Object Example | ||
|
|
||
| ```json | ||
| { | ||
| "userSignedUp": { | ||
| "address": "user.signedup", | ||
| "messages": { | ||
| "userSignedUp": { | ||
| "$ref": "#/components/messages/userSignedUp" | ||
| } | ||
| } | ||
|
|
@@ -554,142 +553,147 @@ Field Pattern | Type | Description | |
| ``` | ||
|
|
||
| ```yaml | ||
| userSignedUp: | ||
| address: 'user.signedup' | ||
| messages: | ||
| userSignedUp: | ||
| $ref: '#/components/messages/userSignedUp' | ||
| ``` | ||
|
|
||
|
|
||
|
|
||
|
|
||
| #### <a name="channelObject"></a>Channel Object | ||
|
|
||
| Describes a shared communication channel. | ||
|
There was a problem hiding this comment. A shared communication channel with who? Am I the only one who feels like this sentence is incomplete in some way... 🤔 There was a problem hiding this comment. We don't know in advance. We only know it's gonna be shared 🤷 |
||
|
|
||
| ##### Fixed Fields | ||
|
|
||
| Field Name | Type | Description | ||
| ---|:---:|--- | ||
| <a name="channelObjectAddress"></a>address | `string` \| `null` | An optional string representation of this channel's address. The address is typically the "topic name", "routing key", "event type", or "path". When `null` or absent, it MUST be interpreted as unknown. This is useful when the address is generated dynamically at runtime or can't be known upfront. It MAY contain [Channel Address Expressions](#channelAddressExpressions). | ||
|
There was a problem hiding this comment. Address is no longer a URL template and, instead, it's just a plain string that supports Channel Address Expressions. |
||
| <a name="channelObjectMessages"></a>messages | [Messages Object](#messagesObject) | A map of the messages that will be sent to this channel by any application at any time. **Every message sent to this channel MUST be valid against one, and only one, of the [message objects](#messageObject) defined in this map.** | ||
| <a name="channelObjectDescription"></a>description | `string` | An optional description of this channel. [CommonMark syntax](https://spec.commonmark.org/) can be used for rich text representation. | ||
| <a name="channelObjectServers"></a>servers | [[Reference Object](#referenceObject)] | An array `$ref` pointers to the definition of the servers in which this channel is available. If `servers` is absent or empty, this channel MUST be available on all the servers defined in the [Servers Object](#serversObject). Please note the `servers` property value MUST be an array of [Reference Objects](#referenceObject) and, therefore, MUST NOT contain an array of [Server Objects](#serverObject). However, it is RECOMMENDED that parsers (or other software) dereference this property for a better development experience. | ||
fmvilas marked this conversation as resolved.
Show resolved
Hide resolved
|
||
| <a name="channelObjectParameters"></a>parameters | [Parameters Object](#parametersObject) | A map of the parameters included in the channel address. It MUST be present only when the address contains [Channel Address Expressions](#channelAddressExpressions). | ||
| <a name="channelObjectBindings"></a>bindings | [Channel Bindings Object](#channelBindingsObject) \| [Reference Object](#referenceObject) | A map where the keys describe the name of the protocol and the values describe protocol-specific definitions for the channel. | ||
| <a name="channelObjectTags"></a>tags | [Tags Object](#tagsObject) | A list of tags for logical grouping of channels. | ||
| <a name="channelObjectExternalDocs"></a>externalDocs | [External Documentation Object](#externalDocumentationObject) | Additional external documentation for this channel. | ||
|
|
||
|
|
||
| This object can be extended with [Specification Extensions](#specificationExtensions). | ||
|
|
||
| ##### Channel Object Example | ||
|
|
||
| ```json | ||
| { | ||
| "address": "users.{userId}", | ||
| "description": "This channel is used to exchange messages about user events.", | ||
| "messages": { | ||
| "userSignedUp": { | ||
| "$ref": "#/components/messages/userSignedUp" | ||
| }, | ||
| "userCompletedOrder": { | ||
| "$ref": "#/components/messages/userCompletedOrder" | ||
| } | ||
| }, | ||
| "parameters": { | ||
| "userId": { | ||
| "$ref": "#/components/parameters/userId" | ||
| } | ||
| }, | ||
| "servers": [ | ||
| { "$ref": "#/servers/rabbitmqInProd" }, | ||
| { "$ref": "#/servers/rabbitmqInStaging" } | ||
| ], | ||
| "bindings": { | ||
| "amqp": { | ||
| "is": "queue", | ||
| "queue": { | ||
| "exclusive": true | ||
| } | ||
| } | ||
| }, | ||
| "tags": [{ | ||
| "name": "user", | ||
| "description": "User-related messages" | ||
| }], | ||
| "externalDocs": { | ||
| "description": "Find more info here", | ||
| "url": "https://example.com" | ||
| } | ||
| } | ||
| ``` | ||
|
|
||
| ```yaml | ||
| address: 'users.{userId}' | ||
| description: This channel is used to exchange messages about user events. | ||
| messages: | ||
| userSignedUp: | ||
| $ref: '#/components/messages/userSignedUp' | ||
| userCompletedOrder: | ||
| $ref: '#/components/messages/userCompletedOrder' | ||
| parameters: | ||
| userId: | ||
| $ref: '#/components/parameters/userId' | ||
| servers: | ||
| - $ref: '#/servers/rabbitmqInProd' | ||
| - $ref: '#/servers/rabbitmqInStaging' | ||
| bindings: | ||
| amqp: | ||
| is: queue | ||
| queue: | ||
| exclusive: true | ||
| tags: | ||
| - name: user | ||
| description: User-related messages | ||
| externalDocs: | ||
| description: 'Find more info here' | ||
| url: 'https://example.com' | ||
| ``` | ||
|
|
||
|
|
||
|
|
||
|
|
||
|
|
||
| #### <a name="channelAddressExpressions"></a>Channel Address Expressions | ||
|
There was a problem hiding this comment. I went all-in defining our own templating rules here. I don't know what I was thinking when I defined the channel address as a URL template in version 2.0.0 😅 Have a look: https://www.rfc-editor.org/rfc/rfc6570#section-2.4.2. |
||
|
|
||
| Channel addresses MAY contain expressions that can be used to define dynamic values. | ||
|
|
||
| Expressions MUST be composed by a name enclosed in curly braces (`{` and `}`). E.g., `{userId}`. | ||
|
|
||
|
|
||
|
|
||
|
|
||
|
|
||
| #### <a name="messagesObject"></a>Messages Object | ||
|
|
||
| Describes a map of messages included in a channel. | ||
|
|
||
| ##### Patterned Fields | ||
|
|
||
| Field Pattern | Type | Description | ||
| ---|:---:|--- | ||
| <a name="messagesObjectId"></a>`{messageId}` | [Message Object](#messageObject) \| [Reference Object](#referenceObject) | The key represents the message identifier. The `messageId` value is **case-sensitive**. Tools and libraries MAY use the `messageId` value to uniquely identify a message, therefore, it is RECOMMENDED to follow common programming naming conventions. | ||
|
|
||
| ##### Messages Object Example | ||
|
|
||
| ```json | ||
| { | ||
| "userSignedUp": { | ||
| "$ref": "#/components/messages/userSignedUp" | ||
| }, | ||
| "userCompletedOrder": { | ||
| "$ref": "#/components/messages/userCompletedOrder" | ||
| } | ||
| } | ||
| ``` | ||
|
|
||
| ```yaml | ||
| userSignedUp: | ||
| $ref: '#/components/messages/userSignedUp' | ||
| userCompletedOrder: | ||
| $ref: '#/components/messages/userCompletedOrder' | ||
| ``` | ||
|
|
||
|
|
||
|
|
@@ -1464,7 +1468,7 @@ Field Name | Type | Description | |
| ---|:---|--- | ||
| <a name="componentsSchemas"></a> schemas | Map[`string`, [Schema Object](#schemaObject) \| [Reference Object](#referenceObject)] | An object to hold reusable [Schema Objects](#schemaObject). | ||
| <a name="componentsServers"></a> servers | Map[`string`, [Server Object](#serverObject) \| [Reference Object](#referenceObject)] | An object to hold reusable [Server Objects](#serverObject). | ||
| <a name="componentsChannels"></a> channels | Map[`string`, [Channel Object](#channelObject) \| [Reference Object](#referenceObject)] | An object to hold reusable [Channel Objects](#channelObject). | ||
| <a name="componentsServerVariables"></a> serverVariables | Map[`string`, [Server Variable Object](#serverVariableObject) \| [Reference Object](#referenceObject)] | An object to hold reusable [Server Variable Objects](#serverVariableObject). | ||
| <a name="componentsMessages"></a> messages | Map[`string`, [Message Object](#messageObject) \| [Reference Object](#referenceObject)] | An object to hold reusable [Message Objects](#messageObject). | ||
| <a name="componentsSecuritySchemes"></a> securitySchemes| Map[`string`, [Security Scheme Object](#securitySchemeObject) \| [Reference Object](#referenceObject)] | An object to hold reusable [Security Scheme Objects](#securitySchemeObject). | ||
|
|
@@ -2554,6 +2558,6 @@ string | `string` | | | | |
| byte | `string` | `byte` | base64 encoded characters | ||
| binary | `string` | `binary` | any sequence of octets | ||
| boolean | `boolean` | | | | ||
| date | `string` | `date` | As defined by `full-date` - [RFC3339](https://www.rfc-editor.org/rfc/rfc3339) | ||
| dateTime | `string` | `date-time` | As defined by `date-time` - [RFC3339](https://www.rfc-editor.org/rfc/rfc3339) | ||
fmvilas marked this conversation as resolved.
Show resolved
Hide resolved
|
||
| password | `string` | `password` | Used to hint UIs the input needs to be obscured. | ||
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Notice
channelsis not required anymore.