From d105626ef6038f88a3e1fe324d407053c314a958 Mon Sep 17 00:00:00 2001 From: Lazzaretti Date: Fri, 26 Jan 2024 14:17:45 +0100 Subject: [PATCH] feat(docs): Add documentation & example that AsyncApi 3 is supported Signed-off-by: Lazzaretti --- .../software-catalog/descriptor-format.md | 2 +- .../examples/apis/streetlights-api.yaml | 204 +++++++++------- plugins/api-docs/README.md | 2 +- .../api-docs/dev/asyncapi-example-api.yaml | 221 ++++++++++-------- 4 files changed, 249 insertions(+), 180 deletions(-) diff --git a/docs/features/software-catalog/descriptor-format.md b/docs/features/software-catalog/descriptor-format.md index 526ba15072..cc2b3d1c7b 100644 --- a/docs/features/software-catalog/descriptor-format.md +++ b/docs/features/software-catalog/descriptor-format.md @@ -838,7 +838,7 @@ The current set of well-known and common values for this field is: - `openapi` - An API definition in YAML or JSON format based on the [OpenAPI](https://swagger.io/specification/) version 2 or version 3 spec. - `asyncapi` - An API definition based on the - [AsyncAPI](https://www.asyncapi.com/docs/reference/specification/latest) spec. + [AsyncAPI](https://www.asyncapi.com/docs/reference/specification/latest) version 2 or version 3 spec. - `graphql` - An API definition based on [GraphQL schemas](https://spec.graphql.org/) for consuming [GraphQL](https://graphql.org/) based APIs. diff --git a/packages/catalog-model/examples/apis/streetlights-api.yaml b/packages/catalog-model/examples/apis/streetlights-api.yaml index 4e0dbb1396..0420f92d05 100644 --- a/packages/catalog-model/examples/apis/streetlights-api.yaml +++ b/packages/catalog-model/examples/apis/streetlights-api.yaml @@ -6,7 +6,7 @@ metadata: tags: - mqtt links: - - url: https://github.com/asyncapi/asyncapi/blob/master/examples/1.2.0/streetlights.yml + - url: https://github.com/asyncapi/spec/master/examples/streetlights-mqtt-asyncapi.ymlhttps://github.com/asyncapi/spec/blob/master/examples/streetlights-mqtt-asyncapi.yml title: Source Code icon: code spec: @@ -14,25 +14,18 @@ spec: lifecycle: production owner: team-c definition: | - asyncapi: 2.0.0 + asyncapi: 3.0.0 info: - title: Streetlights API - version: '1.0.0' - description: | - The Smartylighting Streetlights API allows you to remotely manage the city lights. - - ### Check out its awesome features: - - * Turn a specific streetlight on/off 🌃 - * Dim a specific streetlight 😎 - * Receive real-time information about environmental lighting conditions 📈 + title: Streetlights MQTT API + version: 1.0.0 + description: "The Smartylighting Streetlights API allows you to remotely manage the city lights.\n\n### Check out its awesome features:\n\n* Turn a specific streetlight on/off \U0001F303\n* Dim a specific streetlight \U0001F60E\n* Receive real-time information about environmental lighting conditions \U0001F4C8\n" license: name: Apache 2.0 - url: https://www.apache.org/licenses/LICENSE-2.0 - + url: 'https://www.apache.org/licenses/LICENSE-2.0' + defaultContentType: application/json servers: production: - url: api.streetlights.smartylighting.com:{port} + host: 'test.mosquitto.org:{port}' protocol: mqtt description: Test broker variables: @@ -43,73 +36,131 @@ spec: - '1883' - '8883' security: - - apiKey: [] - - supportedOauthFlows: - - streetlights:on - - streetlights:off - - streetlights:dim - - openIdConnectWellKnown: [] - - defaultContentType: application/json - + - $ref: '#/components/securitySchemes/apiKey' + - type: oauth2 + description: Flows to support OAuth 2.0 + flows: + implicit: + authorizationUrl: 'https://authserver.example/auth' + availableScopes: + 'streetlights:on': Ability to switch lights on + 'streetlights:off': Ability to switch lights off + 'streetlights:dim': Ability to dim the lights + password: + tokenUrl: 'https://authserver.example/token' + availableScopes: + 'streetlights:on': Ability to switch lights on + 'streetlights:off': Ability to switch lights off + 'streetlights:dim': Ability to dim the lights + clientCredentials: + tokenUrl: 'https://authserver.example/token' + availableScopes: + 'streetlights:on': Ability to switch lights on + 'streetlights:off': Ability to switch lights off + 'streetlights:dim': Ability to dim the lights + authorizationCode: + authorizationUrl: 'https://authserver.example/auth' + tokenUrl: 'https://authserver.example/token' + refreshUrl: 'https://authserver.example/refresh' + availableScopes: + 'streetlights:on': Ability to switch lights on + 'streetlights:off': Ability to switch lights off + 'streetlights:dim': Ability to dim the lights + scopes: + - 'streetlights:on' + - 'streetlights:off' + - 'streetlights:dim' + - $ref: '#/components/securitySchemes/openIdConnectWellKnown' + tags: + - name: 'env:production' + description: This environment is meant for production use case + - name: 'kind:remote' + description: This server is a remote server. Not exposed by the application + - name: 'visibility:public' + description: This resource is public and available to everyone channels: - smartylighting/streetlights/1/0/event/{streetlightId}/lighting/measured: + lightingMeasured: + address: 'smartylighting/streetlights/1/0/event/{streetlightId}/lighting/measured' + messages: + lightMeasured: + $ref: '#/components/messages/lightMeasured' description: The topic on which measured values may be produced and consumed. parameters: streetlightId: $ref: '#/components/parameters/streetlightId' - subscribe: - summary: Receive information about environmental lighting conditions of a particular streetlight. - operationId: receiveLightMeasurement - traits: - - $ref: '#/components/operationTraits/kafka' - message: - $ref: '#/components/messages/lightMeasured' - - smartylighting/streetlights/1/0/action/{streetlightId}/turn/on: - parameters: - streetlightId: - $ref: '#/components/parameters/streetlightId' - publish: - operationId: turnOn - traits: - - $ref: '#/components/operationTraits/kafka' - message: + lightTurnOn: + address: 'smartylighting/streetlights/1/0/action/{streetlightId}/turn/on' + messages: + turnOn: $ref: '#/components/messages/turnOnOff' - - smartylighting/streetlights/1/0/action/{streetlightId}/turn/off: parameters: streetlightId: $ref: '#/components/parameters/streetlightId' - publish: - operationId: turnOff - traits: - - $ref: '#/components/operationTraits/kafka' - message: + lightTurnOff: + address: 'smartylighting/streetlights/1/0/action/{streetlightId}/turn/off' + messages: + turnOff: $ref: '#/components/messages/turnOnOff' - - smartylighting/streetlights/1/0/action/{streetlightId}/dim: parameters: streetlightId: $ref: '#/components/parameters/streetlightId' - publish: - operationId: dimLight - traits: - - $ref: '#/components/operationTraits/kafka' - message: + lightsDim: + address: 'smartylighting/streetlights/1/0/action/{streetlightId}/dim' + messages: + dimLight: $ref: '#/components/messages/dimLight' - + parameters: + streetlightId: + $ref: '#/components/parameters/streetlightId' + operations: + receiveLightMeasurement: + action: receive + channel: + $ref: '#/channels/lightingMeasured' + summary: >- + Inform about environmental lighting conditions of a particular + streetlight. + traits: + - $ref: '#/components/operationTraits/mqtt' + messages: + - $ref: '#/channels/lightingMeasured/messages/lightMeasured' + turnOn: + action: send + channel: + $ref: '#/channels/lightTurnOn' + traits: + - $ref: '#/components/operationTraits/mqtt' + messages: + - $ref: '#/channels/lightTurnOn/messages/turnOn' + turnOff: + action: send + channel: + $ref: '#/channels/lightTurnOff' + traits: + - $ref: '#/components/operationTraits/mqtt' + messages: + - $ref: '#/channels/lightTurnOff/messages/turnOff' + dimLight: + action: send + channel: + $ref: '#/channels/lightsDim' + traits: + - $ref: '#/components/operationTraits/mqtt' + messages: + - $ref: '#/channels/lightsDim/messages/dimLight' components: messages: lightMeasured: name: lightMeasured title: Light measured - summary: Inform about environmental lighting conditions for a particular streetlight. + summary: >- + Inform about environmental lighting conditions of a particular + streetlight. contentType: application/json traits: - $ref: '#/components/messageTraits/commonHeaders' payload: - $ref: "#/components/schemas/lightMeasuredPayload" + $ref: '#/components/schemas/lightMeasuredPayload' turnOnOff: name: turnOnOff title: Turn on/off @@ -117,7 +168,7 @@ spec: traits: - $ref: '#/components/messageTraits/commonHeaders' payload: - $ref: "#/components/schemas/turnOnOffPayload" + $ref: '#/components/schemas/turnOnOffPayload' dimLight: name: dimLight title: Dim light @@ -125,8 +176,7 @@ spec: traits: - $ref: '#/components/messageTraits/commonHeaders' payload: - $ref: "#/components/schemas/dimLightPayload" - + $ref: '#/components/schemas/dimLightPayload' schemas: lightMeasuredPayload: type: object @@ -136,18 +186,18 @@ spec: minimum: 0 description: Light intensity measured in lumens. sentAt: - $ref: "#/components/schemas/sentAt" + $ref: '#/components/schemas/sentAt' turnOnOffPayload: type: object properties: command: type: string enum: - - on - - off + - 'on' + - 'off' description: Whether to turn on or off the light. sentAt: - $ref: "#/components/schemas/sentAt" + $ref: '#/components/schemas/sentAt' dimLightPayload: type: object properties: @@ -157,12 +207,11 @@ spec: minimum: 0 maximum: 100 sentAt: - $ref: "#/components/schemas/sentAt" + $ref: '#/components/schemas/sentAt' sentAt: type: string format: date-time description: Date and time when the message was sent. - securitySchemes: apiKey: type: apiKey @@ -174,19 +223,19 @@ spec: flows: implicit: authorizationUrl: 'https://authserver.example/auth' - scopes: + availableScopes: 'streetlights:on': Ability to switch lights on 'streetlights:off': Ability to switch lights off 'streetlights:dim': Ability to dim the lights password: tokenUrl: 'https://authserver.example/token' - scopes: + availableScopes: 'streetlights:on': Ability to switch lights on 'streetlights:off': Ability to switch lights off 'streetlights:dim': Ability to dim the lights clientCredentials: tokenUrl: 'https://authserver.example/token' - scopes: + availableScopes: 'streetlights:on': Ability to switch lights on 'streetlights:off': Ability to switch lights off 'streetlights:dim': Ability to dim the lights @@ -194,20 +243,16 @@ spec: authorizationUrl: 'https://authserver.example/auth' tokenUrl: 'https://authserver.example/token' refreshUrl: 'https://authserver.example/refresh' - scopes: + availableScopes: 'streetlights:on': Ability to switch lights on 'streetlights:off': Ability to switch lights off 'streetlights:dim': Ability to dim the lights openIdConnectWellKnown: type: openIdConnect openIdConnectUrl: 'https://authserver.example/.well-known' - parameters: streetlightId: description: The ID of the streetlight. - schema: - type: string - messageTraits: commonHeaders: headers: @@ -217,9 +262,8 @@ spec: type: integer minimum: 0 maximum: 100 - operationTraits: - kafka: + mqtt: bindings: - kafka: - clientId: my-app-id + mqtt: + qos: 1 diff --git a/plugins/api-docs/README.md b/plugins/api-docs/README.md index 46d9df4628..4d7cc46c24 100644 --- a/plugins/api-docs/README.md +++ b/plugins/api-docs/README.md @@ -13,7 +13,7 @@ The plugin provides a standalone list of APIs, as well as an integration into th Right now, the following API formats are supported: - [OpenAPI](https://swagger.io/specification/) 2 & 3 -- [AsyncAPI](https://www.asyncapi.com/docs/reference/specification/latest) +- [AsyncAPI](https://www.asyncapi.com/docs/reference/specification/latest) 2 & 3 - [GraphQL](https://graphql.org/learn/schema/) Other formats are displayed as plain text, but this can easily be extended. diff --git a/plugins/api-docs/dev/asyncapi-example-api.yaml b/plugins/api-docs/dev/asyncapi-example-api.yaml index 3895006979..931b8fe882 100644 --- a/plugins/api-docs/dev/asyncapi-example-api.yaml +++ b/plugins/api-docs/dev/asyncapi-example-api.yaml @@ -10,25 +10,18 @@ spec: lifecycle: production owner: team-c definition: | - asyncapi: 2.0.0 + asyncapi: 3.0.0 info: - title: Streetlights API - version: '1.0.0' - description: | - The Smartylighting Streetlights API allows you to remotely manage the city lights. - - ### Check out its awesome features: - - * Turn a specific streetlight on/off 🌃 - * Dim a specific streetlight 😎 - * Receive real-time information about environmental lighting conditions 📈 + title: Streetlights MQTT API + version: 1.0.0 + description: "The Smartylighting Streetlights API allows you to remotely manage the city lights.\n\n### Check out its awesome features:\n\n* Turn a specific streetlight on/off \U0001F303\n* Dim a specific streetlight \U0001F60E\n* Receive real-time information about environmental lighting conditions \U0001F4C8\n" license: name: Apache 2.0 - url: https://www.apache.org/licenses/LICENSE-2.0 - + url: 'https://www.apache.org/licenses/LICENSE-2.0' + defaultContentType: application/json servers: production: - url: api.streetlights.smartylighting.com:{port} + host: 'test.mosquitto.org:{port}' protocol: mqtt description: Test broker variables: @@ -39,73 +32,131 @@ spec: - '1883' - '8883' security: - - apiKey: [] - - supportedOauthFlows: - - streetlights:on - - streetlights:off - - streetlights:dim - - openIdConnectWellKnown: [] - - defaultContentType: application/json - + - $ref: '#/components/securitySchemes/apiKey' + - type: oauth2 + description: Flows to support OAuth 2.0 + flows: + implicit: + authorizationUrl: 'https://authserver.example/auth' + availableScopes: + 'streetlights:on': Ability to switch lights on + 'streetlights:off': Ability to switch lights off + 'streetlights:dim': Ability to dim the lights + password: + tokenUrl: 'https://authserver.example/token' + availableScopes: + 'streetlights:on': Ability to switch lights on + 'streetlights:off': Ability to switch lights off + 'streetlights:dim': Ability to dim the lights + clientCredentials: + tokenUrl: 'https://authserver.example/token' + availableScopes: + 'streetlights:on': Ability to switch lights on + 'streetlights:off': Ability to switch lights off + 'streetlights:dim': Ability to dim the lights + authorizationCode: + authorizationUrl: 'https://authserver.example/auth' + tokenUrl: 'https://authserver.example/token' + refreshUrl: 'https://authserver.example/refresh' + availableScopes: + 'streetlights:on': Ability to switch lights on + 'streetlights:off': Ability to switch lights off + 'streetlights:dim': Ability to dim the lights + scopes: + - 'streetlights:on' + - 'streetlights:off' + - 'streetlights:dim' + - $ref: '#/components/securitySchemes/openIdConnectWellKnown' + tags: + - name: 'env:production' + description: This environment is meant for production use case + - name: 'kind:remote' + description: This server is a remote server. Not exposed by the application + - name: 'visibility:public' + description: This resource is public and available to everyone channels: - smartylighting/streetlights/1/0/event/{streetlightId}/lighting/measured: + lightingMeasured: + address: 'smartylighting/streetlights/1/0/event/{streetlightId}/lighting/measured' + messages: + lightMeasured: + $ref: '#/components/messages/lightMeasured' description: The topic on which measured values may be produced and consumed. parameters: streetlightId: $ref: '#/components/parameters/streetlightId' - subscribe: - summary: Receive information about environmental lighting conditions of a particular streetlight. - operationId: receiveLightMeasurement - traits: - - $ref: '#/components/operationTraits/kafka' - message: - $ref: '#/components/messages/lightMeasured' - - smartylighting/streetlights/1/0/action/{streetlightId}/turn/on: - parameters: - streetlightId: - $ref: '#/components/parameters/streetlightId' - publish: - operationId: turnOn - traits: - - $ref: '#/components/operationTraits/kafka' - message: + lightTurnOn: + address: 'smartylighting/streetlights/1/0/action/{streetlightId}/turn/on' + messages: + turnOn: $ref: '#/components/messages/turnOnOff' - - smartylighting/streetlights/1/0/action/{streetlightId}/turn/off: parameters: streetlightId: $ref: '#/components/parameters/streetlightId' - publish: - operationId: turnOff - traits: - - $ref: '#/components/operationTraits/kafka' - message: + lightTurnOff: + address: 'smartylighting/streetlights/1/0/action/{streetlightId}/turn/off' + messages: + turnOff: $ref: '#/components/messages/turnOnOff' - - smartylighting/streetlights/1/0/action/{streetlightId}/dim: parameters: streetlightId: $ref: '#/components/parameters/streetlightId' - publish: - operationId: dimLight - traits: - - $ref: '#/components/operationTraits/kafka' - message: + lightsDim: + address: 'smartylighting/streetlights/1/0/action/{streetlightId}/dim' + messages: + dimLight: $ref: '#/components/messages/dimLight' - + parameters: + streetlightId: + $ref: '#/components/parameters/streetlightId' + operations: + receiveLightMeasurement: + action: receive + channel: + $ref: '#/channels/lightingMeasured' + summary: >- + Inform about environmental lighting conditions of a particular + streetlight. + traits: + - $ref: '#/components/operationTraits/mqtt' + messages: + - $ref: '#/channels/lightingMeasured/messages/lightMeasured' + turnOn: + action: send + channel: + $ref: '#/channels/lightTurnOn' + traits: + - $ref: '#/components/operationTraits/mqtt' + messages: + - $ref: '#/channels/lightTurnOn/messages/turnOn' + turnOff: + action: send + channel: + $ref: '#/channels/lightTurnOff' + traits: + - $ref: '#/components/operationTraits/mqtt' + messages: + - $ref: '#/channels/lightTurnOff/messages/turnOff' + dimLight: + action: send + channel: + $ref: '#/channels/lightsDim' + traits: + - $ref: '#/components/operationTraits/mqtt' + messages: + - $ref: '#/channels/lightsDim/messages/dimLight' components: messages: lightMeasured: name: lightMeasured title: Light measured - summary: Inform about environmental lighting conditions for a particular streetlight. + summary: >- + Inform about environmental lighting conditions of a particular + streetlight. contentType: application/json traits: - $ref: '#/components/messageTraits/commonHeaders' payload: - $ref: "#/components/schemas/lightMeasuredPayload" + $ref: '#/components/schemas/lightMeasuredPayload' turnOnOff: name: turnOnOff title: Turn on/off @@ -113,7 +164,7 @@ spec: traits: - $ref: '#/components/messageTraits/commonHeaders' payload: - $ref: "#/components/schemas/turnOnOffPayload" + $ref: '#/components/schemas/turnOnOffPayload' dimLight: name: dimLight title: Dim light @@ -121,8 +172,7 @@ spec: traits: - $ref: '#/components/messageTraits/commonHeaders' payload: - $ref: "#/components/schemas/dimLightPayload" - + $ref: '#/components/schemas/dimLightPayload' schemas: lightMeasuredPayload: type: object @@ -132,22 +182,18 @@ spec: minimum: 0 description: Light intensity measured in lumens. sentAt: - $ref: "#/components/schemas/sentAt" - sentBy: - $ref: "#/components/schemas/sentBy" + $ref: '#/components/schemas/sentAt' turnOnOffPayload: type: object properties: command: type: string enum: - - on - - off + - 'on' + - 'off' description: Whether to turn on or off the light. sentAt: - $ref: "#/components/schemas/sentAt" - sentBy: - $ref: "#/components/schemas/sentBy" + $ref: '#/components/schemas/sentAt' dimLightPayload: type: object properties: @@ -157,27 +203,11 @@ spec: minimum: 0 maximum: 100 sentAt: - $ref: "#/components/schemas/sentAt" - sentBy: - $ref: "#/components/schemas/sentBy" + $ref: '#/components/schemas/sentAt' sentAt: type: string format: date-time description: Date and time when the message was sent. - sentBy: - type: object - description: Description of the message sender. - properties: - name: - type: string - description: Name of the sender. - type: - type: string - description: Type of the sender. - enum: - - user - - machine - securitySchemes: apiKey: type: apiKey @@ -189,19 +219,19 @@ spec: flows: implicit: authorizationUrl: 'https://authserver.example/auth' - scopes: + availableScopes: 'streetlights:on': Ability to switch lights on 'streetlights:off': Ability to switch lights off 'streetlights:dim': Ability to dim the lights password: tokenUrl: 'https://authserver.example/token' - scopes: + availableScopes: 'streetlights:on': Ability to switch lights on 'streetlights:off': Ability to switch lights off 'streetlights:dim': Ability to dim the lights clientCredentials: tokenUrl: 'https://authserver.example/token' - scopes: + availableScopes: 'streetlights:on': Ability to switch lights on 'streetlights:off': Ability to switch lights off 'streetlights:dim': Ability to dim the lights @@ -209,20 +239,16 @@ spec: authorizationUrl: 'https://authserver.example/auth' tokenUrl: 'https://authserver.example/token' refreshUrl: 'https://authserver.example/refresh' - scopes: + availableScopes: 'streetlights:on': Ability to switch lights on 'streetlights:off': Ability to switch lights off 'streetlights:dim': Ability to dim the lights openIdConnectWellKnown: type: openIdConnect openIdConnectUrl: 'https://authserver.example/.well-known' - parameters: streetlightId: description: The ID of the streetlight. - schema: - type: string - messageTraits: commonHeaders: headers: @@ -232,9 +258,8 @@ spec: type: integer minimum: 0 maximum: 100 - operationTraits: - kafka: + mqtt: bindings: - kafka: - clientId: my-app-id + mqtt: + qos: 1