-
-
Notifications
You must be signed in to change notification settings - Fork 280
Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
docs: separate streetlight examples for Kafka and MQTT (#548)
Main motivation of this was to provide a place to demonstrate the new Kafka-specific security schemes introduced in AsyncAPI 2.1.0. It was also a chance to remove the Kafka bindings from the otherwise-MQTT sample. The need for this was discussed in #502 Contributes to: #466 Signed-off-by: Dale Lane <[email protected]>
- Loading branch information
Showing
2 changed files
with
372 additions
and
0 deletions.
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 |
|---|---|---|
| @@ -0,0 +1,163 @@ | ||
| asyncapi: '2.1.0' | ||
| info: | ||
| title: Streetlights Kafka 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 📈 | ||
| license: | ||
| name: Apache 2.0 | ||
| url: https://www.apache.org/licenses/LICENSE-2.0 | ||
|
|
||
| servers: | ||
| test: | ||
| url: test.mykafkacluster.org:8092 | ||
| protocol: kafka-secure | ||
| description: Test broker | ||
| security: | ||
| - saslScram: [] | ||
|
|
||
| defaultContentType: application/json | ||
|
|
||
| channels: | ||
| smartylighting/streetlights/1/0/event/{streetlightId}/lighting/measured: | ||
| description: The topic on which measured values may be produced and consumed. | ||
| parameters: | ||
| streetlightId: | ||
| $ref: '#/components/parameters/streetlightId' | ||
| publish: | ||
| summary: Inform 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' | ||
| subscribe: | ||
| operationId: turnOn | ||
| traits: | ||
| - $ref: '#/components/operationTraits/kafka' | ||
| message: | ||
| $ref: '#/components/messages/turnOnOff' | ||
|
|
||
| smartylighting/streetlights/1/0/action/{streetlightId}/turn/off: | ||
| parameters: | ||
| streetlightId: | ||
| $ref: '#/components/parameters/streetlightId' | ||
| subscribe: | ||
| operationId: turnOff | ||
| traits: | ||
| - $ref: '#/components/operationTraits/kafka' | ||
| message: | ||
| $ref: '#/components/messages/turnOnOff' | ||
|
|
||
| smartylighting/streetlights/1/0/action/{streetlightId}/dim: | ||
| parameters: | ||
| streetlightId: | ||
| $ref: '#/components/parameters/streetlightId' | ||
| subscribe: | ||
| operationId: dimLight | ||
| traits: | ||
| - $ref: '#/components/operationTraits/kafka' | ||
| message: | ||
| $ref: '#/components/messages/dimLight' | ||
|
|
||
| components: | ||
| messages: | ||
| lightMeasured: | ||
| name: lightMeasured | ||
| title: Light measured | ||
| summary: Inform about environmental lighting conditions of a particular streetlight. | ||
| contentType: application/json | ||
| traits: | ||
| - $ref: '#/components/messageTraits/commonHeaders' | ||
| payload: | ||
| $ref: "#/components/schemas/lightMeasuredPayload" | ||
| turnOnOff: | ||
| name: turnOnOff | ||
| title: Turn on/off | ||
| summary: Command a particular streetlight to turn the lights on or off. | ||
| traits: | ||
| - $ref: '#/components/messageTraits/commonHeaders' | ||
| payload: | ||
| $ref: "#/components/schemas/turnOnOffPayload" | ||
| dimLight: | ||
| name: dimLight | ||
| title: Dim light | ||
| summary: Command a particular streetlight to dim the lights. | ||
| traits: | ||
| - $ref: '#/components/messageTraits/commonHeaders' | ||
| payload: | ||
| $ref: "#/components/schemas/dimLightPayload" | ||
|
|
||
| schemas: | ||
| lightMeasuredPayload: | ||
| type: object | ||
| properties: | ||
| lumens: | ||
| type: integer | ||
| minimum: 0 | ||
| description: Light intensity measured in lumens. | ||
| sentAt: | ||
| $ref: "#/components/schemas/sentAt" | ||
| turnOnOffPayload: | ||
| type: object | ||
| properties: | ||
| command: | ||
| type: string | ||
| enum: | ||
| - on | ||
| - off | ||
| description: Whether to turn on or off the light. | ||
| sentAt: | ||
| $ref: "#/components/schemas/sentAt" | ||
| dimLightPayload: | ||
| type: object | ||
| properties: | ||
| percentage: | ||
| type: integer | ||
| description: Percentage to which the light should be dimmed to. | ||
| minimum: 0 | ||
| maximum: 100 | ||
| sentAt: | ||
| $ref: "#/components/schemas/sentAt" | ||
| sentAt: | ||
| type: string | ||
| format: date-time | ||
| description: Date and time when the message was sent. | ||
|
|
||
| securitySchemes: | ||
| saslScram: | ||
| type: scramSha256 | ||
| description: Provide your username and password for SASL/SCRAM authentication | ||
|
|
||
| parameters: | ||
| streetlightId: | ||
| description: The ID of the streetlight. | ||
| schema: | ||
| type: string | ||
|
|
||
| messageTraits: | ||
| commonHeaders: | ||
| headers: | ||
| type: object | ||
| properties: | ||
| my-app-header: | ||
| type: integer | ||
| minimum: 0 | ||
| maximum: 100 | ||
|
|
||
| operationTraits: | ||
| kafka: | ||
| bindings: | ||
| kafka: | ||
| clientId: my-app-id |
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 |
|---|---|---|
| @@ -0,0 +1,209 @@ | ||
| asyncapi: '2.1.0' | ||
| info: | ||
| title: Streetlights MQTT 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 📈 | ||
| license: | ||
| name: Apache 2.0 | ||
| url: https://www.apache.org/licenses/LICENSE-2.0 | ||
|
|
||
| servers: | ||
| production: | ||
| url: test.mosquitto.org:{port} | ||
| protocol: mqtt | ||
| description: Test broker | ||
| variables: | ||
| port: | ||
| description: Secure connection (TLS) is available through port 8883. | ||
| default: '1883' | ||
| enum: | ||
| - '1883' | ||
| - '8883' | ||
| security: | ||
| - apiKey: [] | ||
| - supportedOauthFlows: | ||
| - streetlights:on | ||
| - streetlights:off | ||
| - streetlights:dim | ||
| - openIdConnectWellKnown: [] | ||
|
|
||
| defaultContentType: application/json | ||
|
|
||
| channels: | ||
| smartylighting/streetlights/1/0/event/{streetlightId}/lighting/measured: | ||
| description: The topic on which measured values may be produced and consumed. | ||
| parameters: | ||
| streetlightId: | ||
| $ref: '#/components/parameters/streetlightId' | ||
| publish: | ||
| summary: Inform about environmental lighting conditions of a particular streetlight. | ||
| operationId: receiveLightMeasurement | ||
| traits: | ||
| - $ref: '#/components/operationTraits/mqtt' | ||
| message: | ||
| $ref: '#/components/messages/lightMeasured' | ||
|
|
||
| smartylighting/streetlights/1/0/action/{streetlightId}/turn/on: | ||
| parameters: | ||
| streetlightId: | ||
| $ref: '#/components/parameters/streetlightId' | ||
| subscribe: | ||
| operationId: turnOn | ||
| traits: | ||
| - $ref: '#/components/operationTraits/mqtt' | ||
| message: | ||
| $ref: '#/components/messages/turnOnOff' | ||
|
|
||
| smartylighting/streetlights/1/0/action/{streetlightId}/turn/off: | ||
| parameters: | ||
| streetlightId: | ||
| $ref: '#/components/parameters/streetlightId' | ||
| subscribe: | ||
| operationId: turnOff | ||
| traits: | ||
| - $ref: '#/components/operationTraits/mqtt' | ||
| message: | ||
| $ref: '#/components/messages/turnOnOff' | ||
|
|
||
| smartylighting/streetlights/1/0/action/{streetlightId}/dim: | ||
| parameters: | ||
| streetlightId: | ||
| $ref: '#/components/parameters/streetlightId' | ||
| subscribe: | ||
| operationId: dimLight | ||
| traits: | ||
| - $ref: '#/components/operationTraits/mqtt' | ||
| message: | ||
| $ref: '#/components/messages/dimLight' | ||
|
|
||
| components: | ||
| messages: | ||
| lightMeasured: | ||
| name: lightMeasured | ||
| title: Light measured | ||
| summary: Inform about environmental lighting conditions of a particular streetlight. | ||
| contentType: application/json | ||
| traits: | ||
| - $ref: '#/components/messageTraits/commonHeaders' | ||
| payload: | ||
| $ref: "#/components/schemas/lightMeasuredPayload" | ||
| turnOnOff: | ||
| name: turnOnOff | ||
| title: Turn on/off | ||
| summary: Command a particular streetlight to turn the lights on or off. | ||
| traits: | ||
| - $ref: '#/components/messageTraits/commonHeaders' | ||
| payload: | ||
| $ref: "#/components/schemas/turnOnOffPayload" | ||
| dimLight: | ||
| name: dimLight | ||
| title: Dim light | ||
| summary: Command a particular streetlight to dim the lights. | ||
| traits: | ||
| - $ref: '#/components/messageTraits/commonHeaders' | ||
| payload: | ||
| $ref: "#/components/schemas/dimLightPayload" | ||
|
|
||
| schemas: | ||
| lightMeasuredPayload: | ||
| type: object | ||
| properties: | ||
| lumens: | ||
| type: integer | ||
| minimum: 0 | ||
| description: Light intensity measured in lumens. | ||
| sentAt: | ||
| $ref: "#/components/schemas/sentAt" | ||
| turnOnOffPayload: | ||
| type: object | ||
| properties: | ||
| command: | ||
| type: string | ||
| enum: | ||
| - on | ||
| - off | ||
| description: Whether to turn on or off the light. | ||
| sentAt: | ||
| $ref: "#/components/schemas/sentAt" | ||
| dimLightPayload: | ||
| type: object | ||
| properties: | ||
| percentage: | ||
| type: integer | ||
| description: Percentage to which the light should be dimmed to. | ||
| minimum: 0 | ||
| maximum: 100 | ||
| sentAt: | ||
| $ref: "#/components/schemas/sentAt" | ||
| sentAt: | ||
| type: string | ||
| format: date-time | ||
| description: Date and time when the message was sent. | ||
|
|
||
| securitySchemes: | ||
| apiKey: | ||
| type: apiKey | ||
| in: user | ||
| description: Provide your API key as the user and leave the password empty. | ||
| supportedOauthFlows: | ||
| type: oauth2 | ||
| description: Flows to support OAuth 2.0 | ||
| flows: | ||
| implicit: | ||
| authorizationUrl: 'https://authserver.example/auth' | ||
| scopes: | ||
| '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: | ||
| '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: | ||
| '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' | ||
| scopes: | ||
| '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: | ||
| type: object | ||
| properties: | ||
| my-app-header: | ||
| type: integer | ||
| minimum: 0 | ||
| maximum: 100 | ||
|
|
||
| operationTraits: | ||
| mqtt: | ||
| bindings: | ||
| mqtt: | ||
| qos: 1 |