Merge pull request #22536 from Lazzaretti/feature/asyncapi3
feat(docs): Add documentation & example that AsyncApi 3 is supported
This commit is contained in:
Patrik Oldsberg
@@ -16,7 +16,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.
|
||||
|
||||
@@ -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
|
||||
|
||||
Reference in New Issue
Block a user