From 49f0d641d6f9bcd909a2d24a2bdedab3c14de203 Mon Sep 17 00:00:00 2001 From: "jonas-lt@live.dk" Date: Tue, 13 Jun 2023 19:43:52 +0200 Subject: [PATCH 1/4] adapt readme --- anypointmq/README.md | 15 ++++++++------- 1 file changed, 8 insertions(+), 7 deletions(-) diff --git a/anypointmq/README.md b/anypointmq/README.md index a56540a4..440fac90 100644 --- a/anypointmq/README.md +++ b/anypointmq/README.md @@ -7,7 +7,7 @@ This document defines how to describe Anypoint MQ-specific information in AsyncA ## Versions -The version of this bindings specification is `0.0.1`. +The version of this bindings specification is `1.0.0`. This is also the `bindingVersion` for all binding objects defined by this specification. In any given binding object, `latest` MAY alternatively be used to refer to the currently latest published version of this bindings specification. @@ -28,7 +28,8 @@ The fields of the standard [Server Object](https://github.com/asyncapi/spec/blob Server Object Field Name | Values for Anypoint MQ Protocol | Description ---|:---|:--- `protocol` | `anypointmq` | **REQUIRED**. MUST be `anypointmq` for the scope of this specification. -`url` | e.g., `https://mq-us-east-1.anypoint.mulesoft.com/api` | **REQUIRED**. MUST be the endpoint URL of the Anypoint MQ Broker REST API _excluding_ the final major version indicator (e.g., `v1`). Valid examples are `https://mq-us-east-1.anypoint.mulesoft.com/api` and `https://mq-eu-central-1.eu1.anypoint.mulesoft.com/api` (and _not_ `https://.../api/v1`). +`host` | e.g., `https://mq-us-east-1.anypoint.mulesoft.com` | **REQUIRED**. MUST be the endpoint HOST part of the URL of the Anypoint MQ Broker REST API. Valid examples are `https://mq-us-east-1.anypoint.mulesoft.com` and `https://mq-eu-central-1.eu1.anypoint.mulesoft.com` (and _not_ `https://mq-us-east-1.anypoint.mulesoft.com/api`, or `https://.../api/v1`). +`pathname` | e.g., `/api` | **REQUIRED**. MUST be the endpoint path part of the URL of the Anypoint MQ Broker REST API _excluding_ the final major version indicator (e.g., `v1`). Valid examples are `/api` and (and _not_ `https://.../api/v1`). `protocolVersion` | e.g., `v1` | **OPTIONAL**, defaults to `v1`. If present MUST be the major version indicator of the Anypoint MQ Broker REST API omitted from the `url`, e.g. `v1`. `security` | suitably configured OAuth 2.0 client credentials grant type | **REQUIRED**. Authentication against the MuleSoft-hosted Anypoint MQ message brokers uses the OAuth 2.0 client credentials grant type. At runtime, the client ID and client secret values of an Anypoint MQ client app must be supplied. Also, the OAuth 2.0 scopes are currently not client-configurable. The `security` field of the server object MUST correctly match these constraints. @@ -72,7 +73,7 @@ channels: anypointmq: destination: user-signup-exchg destinationType: exchange - bindingVersion: '0.0.1' + bindingVersion: '1.0.0' subscribe: #... ``` @@ -128,7 +129,7 @@ channels: properties: messageId: type: string - bindingVersion: '0.0.1' + bindingVersion: '1.0.0' ``` ## Complete Example @@ -162,7 +163,7 @@ servers: - oauthProd: [] bindings: anypointmq: - bindingVersion: '0.0.1' + bindingVersion: '1.0.0' channels: user/signup: @@ -172,7 +173,7 @@ channels: anypointmq: destination: user-signup-queue destinationType: fifo-queue - bindingVersion: '0.0.1' + bindingVersion: '1.0.0' publish: operationId: signUpUser description: | @@ -201,7 +202,7 @@ channels: properties: messageId: type: string - bindingVersion: '0.0.1' + bindingVersion: '1.0.0' components: securitySchemes: From 814f5fa4143991fca176ba569aab6722782ecf50 Mon Sep 17 00:00:00 2001 From: "jonas-lt@live.dk" Date: Thu, 22 Jun 2023 14:55:12 +0200 Subject: [PATCH 2/4] adapt examples and docs --- anypointmq/README.md | 116 +++++++++++++++++++++++++------------------ 1 file changed, 67 insertions(+), 49 deletions(-) diff --git a/anypointmq/README.md b/anypointmq/README.md index 440fac90..8e9ee6e3 100644 --- a/anypointmq/README.md +++ b/anypointmq/README.md @@ -7,7 +7,7 @@ This document defines how to describe Anypoint MQ-specific information in AsyncA ## Versions -The version of this bindings specification is `1.0.0`. +The version of this bindings specification is `0.1.0`. This is also the `bindingVersion` for all binding objects defined by this specification. In any given binding object, `latest` MAY alternatively be used to refer to the currently latest published version of this bindings specification. @@ -55,27 +55,30 @@ Note that an Anypoint MQ exchange can only be sent to, not received from. To rec ### Examples -The following example shows a `channels` object with two channels, the second having a channel binding object for `anypointmq`: +The following example shows two channels where does not apply any bindings and the second one applying `anyointmq` bindings. ```yaml channels: - user/signup: + userSignup: + address: 'user/signup' description: | This application receives command messages from this channel about users to sign up. Minimal configuration, omitting a channel binding object. - publish: + messages: #... - user/signedup: + + userSignup: + address: 'user/signup' description: | This application sends events to this channel about users that have signed up. Explicitly provides a channel binding object. + messages: + #... bindings: anypointmq: destination: user-signup-exchg destinationType: exchange - bindingVersion: '1.0.0' - subscribe: - #... + bindingVersion: '0.1.0' ``` @@ -86,7 +89,7 @@ This object MUST NOT contain any properties. Its name is reserved for future use ## Message Binding Object -The Anypoint MQ [Message Binding Object](https://github.com/asyncapi/spec/blob/master/spec/asyncapi.md#message-bindings-object) is defined by a [JSON Schema](json_schemas/message.json), which defines these fields: +The Anypoint MQ [Message Binding Object](https://github.com/asyncapi/spec/blob/master/spec/asyncapi.md#message-bindings-object) defines these fields: Field Name | Type | Description ---|:---:|--- @@ -102,13 +105,14 @@ The following example shows a `channels` object with two channels, each having o ```yaml channels: - user/signup: - publish: - message: - #... - user/signedup: - subscribe: - message: + userSignup: + address: 'user/signup' + messages: + #... + userSignup: + address: 'user/signup' + messages: + userSignupMessage: headers: type: object properties: @@ -129,7 +133,7 @@ channels: properties: messageId: type: string - bindingVersion: '1.0.0' + bindingVersion: '0.1.0' ``` ## Complete Example @@ -137,48 +141,43 @@ channels: The following is a complete, simple AsyncAPI document illustrating the usage of all binding objects defined in this bindings specification, with all their fields. ```yaml -asyncapi: '2.0.0' +asyncapi: 3.0.0 info: title: Example with Anypoint MQ - version: '0.0.1' - + version: 0.0.1 servers: development: + host: mq-us-east-1.anypoint.mulesoft.com + pathname: /api protocol: anypointmq protocolVersion: v1 - url: https://mq-us-east-1.anypoint.mulesoft.com/api - description: | - Anypoint MQ broker for development, in the US East (N. Virginia) runtime plane + description: > + Anypoint MQ broker for development, in the US East (N. Virginia) runtime + plane + under management of the US control plane. security: - - oauthDev: [] + - $ref: '#/components/securitySchemes/oauthDev' production: + host: mq-eu-central-1.eu1.anypoint.mulesoft.com + pathname: /api protocol: anypointmq protocolVersion: v1 - url: https://mq-eu-central-1.eu1.anypoint.mulesoft.com/api - description: | - Anypoint MQ broker for production, in the EU Central (Frankfurt) runtime plane + description: > + Anypoint MQ broker for production, in the EU Central (Frankfurt) runtime + plane + under management of the EU control plane. security: - - oauthProd: [] + - $ref: '#/components/securitySchemes/oauthProd' bindings: anypointmq: - bindingVersion: '1.0.0' - + bindingVersion: 0.1.0 channels: user/signup: - description: | - This application receives command messages from this channel about users to sign up. - bindings: - anypointmq: - destination: user-signup-queue - destinationType: fifo-queue - bindingVersion: '1.0.0' - publish: - operationId: signUpUser - description: | - This application receives command messages via this operation about users to sign up. - message: + address: user/signup + messages: + signUpUser.message: contentType: application/json headers: type: object @@ -193,7 +192,9 @@ channels: type: string minLength: 3 correlationId: - description: Correlation ID is specified as a header and transmitted in the Anypoint MQ message properties section + description: >- + Correlation ID is specified as a header and transmitted in the + Anypoint MQ message properties section location: $message.header#/correlationId bindings: anypointmq: @@ -202,20 +203,37 @@ channels: properties: messageId: type: string - bindingVersion: '1.0.0' - + bindingVersion: 0.1.0 + description: > + This application receives command messages from this channel about users + to sign up. + bindings: + anypointmq: + destination: user-signup-queue + destinationType: fifo-queue + bindingVersion: 0.1.0 +operations: + signUpUser: + action: receive + channel: + $ref: '#/channels/user~1signup' + description: > + This application receives command messages via this operation about users + to sign up. + messages: + - $ref: '#/channels/user~1signup/messages/signUpUser.message' components: securitySchemes: oauthDev: type: oauth2 flows: clientCredentials: - tokenUrl: https://mq-us-east-1.anypoint.mulesoft.com/api/v1/authorize - scopes: {} + tokenUrl: 'https://mq-us-east-1.anypoint.mulesoft.com/api/v1/authorize' + availableScopes: {} oauthProd: type: oauth2 flows: clientCredentials: - tokenUrl: https://mq-eu-central-1.eu1.anypoint.mulesoft.com/api/v1/authorize - scopes: {} + tokenUrl: 'https://mq-eu-central-1.eu1.anypoint.mulesoft.com/api/v1/authorize' + availableScopes: {} ``` From 51a3a5ac1f9df3a2f98f2dd11552b6da334c5d81 Mon Sep 17 00:00:00 2001 From: Jonas Lagoni Date: Thu, 22 Jun 2023 15:05:05 +0200 Subject: [PATCH 3/4] Update anypointmq/README.md --- anypointmq/README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/anypointmq/README.md b/anypointmq/README.md index 8e9ee6e3..2170b3b7 100644 --- a/anypointmq/README.md +++ b/anypointmq/README.md @@ -229,7 +229,7 @@ components: flows: clientCredentials: tokenUrl: 'https://mq-us-east-1.anypoint.mulesoft.com/api/v1/authorize' - availableScopes: {} + scopes: {} oauthProd: type: oauth2 flows: From 5d3b77f54e0311452f4962c1ca703059f8e18086 Mon Sep 17 00:00:00 2001 From: Jonas Lagoni Date: Thu, 22 Jun 2023 15:05:22 +0200 Subject: [PATCH 4/4] Update anypointmq/README.md --- anypointmq/README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/anypointmq/README.md b/anypointmq/README.md index 2170b3b7..dedade72 100644 --- a/anypointmq/README.md +++ b/anypointmq/README.md @@ -235,5 +235,5 @@ components: flows: clientCredentials: tokenUrl: 'https://mq-eu-central-1.eu1.anypoint.mulesoft.com/api/v1/authorize' - availableScopes: {} + scopes: {} ```