backstage

1
apiVersion: backstage.io/v1alpha1
2
kind: API
3
metadata:
4
  name: streetlights
5
  description: The Smartylighting Streetlights API allows you to remotely manage the city lights.
6
  tags:
7
    - mqtt
8
spec:
9
  type: asyncapi
10
  lifecycle: production
11
  owner: team-c
12
  definition: |
13
    asyncapi: 3.0.0
14
    info:
15
      title: Streetlights MQTT API
16
      version: 1.0.0
17
      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"
18
      license:
19
        name: Apache 2.0
20
        url: 'https://www.apache.org/licenses/LICENSE-2.0'
21
    defaultContentType: application/json
22
    servers:
23
      production:
24
        host: 'test.mosquitto.org:{port}'
25
        protocol: mqtt
26
        description: Test broker
27
        variables:
28
          port:
29
            description: Secure connection (TLS) is available through port 8883.
30
            default: '1883'
31
            enum:
32
              - '1883'
33
              - '8883'
34
        security:
35
          - $ref: '#/components/securitySchemes/apiKey'
36
          - type: oauth2
37
            description: Flows to support OAuth 2.0
38
            flows:
39
              implicit:
40
                authorizationUrl: 'https://authserver.example/auth'
41
                availableScopes:
42
                  'streetlights:on': Ability to switch lights on
43
                  'streetlights:off': Ability to switch lights off
44
                  'streetlights:dim': Ability to dim the lights
45
              password:
46
                tokenUrl: 'https://authserver.example/token'
47
                availableScopes:
48
                  'streetlights:on': Ability to switch lights on
49
                  'streetlights:off': Ability to switch lights off
50
                  'streetlights:dim': Ability to dim the lights
51
              clientCredentials:
52
                tokenUrl: 'https://authserver.example/token'
53
                availableScopes:
54
                  'streetlights:on': Ability to switch lights on
55
                  'streetlights:off': Ability to switch lights off
56
                  'streetlights:dim': Ability to dim the lights
57
              authorizationCode:
58
                authorizationUrl: 'https://authserver.example/auth'
59
                tokenUrl: 'https://authserver.example/token'
60
                refreshUrl: 'https://authserver.example/refresh'
61
                availableScopes:
62
                  'streetlights:on': Ability to switch lights on
63
                  'streetlights:off': Ability to switch lights off
64
                  'streetlights:dim': Ability to dim the lights
65
            scopes:
66
              - 'streetlights:on'
67
              - 'streetlights:off'
68
              - 'streetlights:dim'
69
          - $ref: '#/components/securitySchemes/openIdConnectWellKnown'
70
        tags:
71
          - name: 'env:production'
72
            description: This environment is meant for production use case
73
          - name: 'kind:remote'
74
            description: This server is a remote server. Not exposed by the application
75
          - name: 'visibility:public'
76
            description: This resource is public and available to everyone
77
    channels:
78
      lightingMeasured:
79
        address: 'smartylighting/streetlights/1/0/event/{streetlightId}/lighting/measured'
80
        messages:
81
          lightMeasured:
82
            $ref: '#/components/messages/lightMeasured'
83
        description: The topic on which measured values may be produced and consumed.
84
        parameters:
85
          streetlightId:
86
            $ref: '#/components/parameters/streetlightId'
87
      lightTurnOn:
88
        address: 'smartylighting/streetlights/1/0/action/{streetlightId}/turn/on'
89
        messages:
90
          turnOn:
91
            $ref: '#/components/messages/turnOnOff'
92
        parameters:
93
          streetlightId:
94
            $ref: '#/components/parameters/streetlightId'
95
      lightTurnOff:
96
        address: 'smartylighting/streetlights/1/0/action/{streetlightId}/turn/off'
97
        messages:
98
          turnOff:
99
            $ref: '#/components/messages/turnOnOff'
100
        parameters:
101
          streetlightId:
102
            $ref: '#/components/parameters/streetlightId'
103
      lightsDim:
104
        address: 'smartylighting/streetlights/1/0/action/{streetlightId}/dim'
105
        messages:
106
          dimLight:
107
            $ref: '#/components/messages/dimLight'
108
        parameters:
109
          streetlightId:
110
            $ref: '#/components/parameters/streetlightId'
111
    operations:
112
      receiveLightMeasurement:
113
        action: receive
114
        channel:
115
          $ref: '#/channels/lightingMeasured'
116
        summary: >-
117
          Inform about environmental lighting conditions of a particular
118
          streetlight.
119
        traits:
120
          - $ref: '#/components/operationTraits/mqtt'
121
        messages:
122
          - $ref: '#/channels/lightingMeasured/messages/lightMeasured'
123
      turnOn:
124
        action: send
125
        channel:
126
          $ref: '#/channels/lightTurnOn'
127
        traits:
128
          - $ref: '#/components/operationTraits/mqtt'
129
        messages:
130
          - $ref: '#/channels/lightTurnOn/messages/turnOn'
131
      turnOff:
132
        action: send
133
        channel:
134
          $ref: '#/channels/lightTurnOff'
135
        traits:
136
          - $ref: '#/components/operationTraits/mqtt'
137
        messages:
138
          - $ref: '#/channels/lightTurnOff/messages/turnOff'
139
      dimLight:
140
        action: send
141
        channel:
142
          $ref: '#/channels/lightsDim'
143
        traits:
144
          - $ref: '#/components/operationTraits/mqtt'
145
        messages:
146
          - $ref: '#/channels/lightsDim/messages/dimLight'
147
    components:
148
      messages:
149
        lightMeasured:
150
          name: lightMeasured
151
          title: Light measured
152
          summary: >-
153
            Inform about environmental lighting conditions of a particular
154
            streetlight.
155
          contentType: application/json
156
          traits:
157
            - $ref: '#/components/messageTraits/commonHeaders'
158
          payload:
159
            $ref: '#/components/schemas/lightMeasuredPayload'
160
        turnOnOff:
161
          name: turnOnOff
162
          title: Turn on/off
163
          summary: Command a particular streetlight to turn the lights on or off.
164
          traits:
165
            - $ref: '#/components/messageTraits/commonHeaders'
166
          payload:
167
            $ref: '#/components/schemas/turnOnOffPayload'
168
        dimLight:
169
          name: dimLight
170
          title: Dim light
171
          summary: Command a particular streetlight to dim the lights.
172
          traits:
173
            - $ref: '#/components/messageTraits/commonHeaders'
174
          payload:
175
            $ref: '#/components/schemas/dimLightPayload'
176
      schemas:
177
        lightMeasuredPayload:
178
          type: object
179
          properties:
180
            lumens:
181
              type: integer
182
              minimum: 0
183
              description: Light intensity measured in lumens.
184
            sentAt:
185
              $ref: '#/components/schemas/sentAt'
186
        turnOnOffPayload:
187
          type: object
188
          properties:
189
            command:
190
              type: string
191
              enum:
192
                - 'on'
193
                - 'off'
194
              description: Whether to turn on or off the light.
195
            sentAt:
196
              $ref: '#/components/schemas/sentAt'
197
        dimLightPayload:
198
          type: object
199
          properties:
200
            percentage:
201
              type: integer
202
              description: Percentage to which the light should be dimmed to.
203
              minimum: 0
204
              maximum: 100
205
            sentAt:
206
              $ref: '#/components/schemas/sentAt'
207
        sentAt:
208
          type: string
209
          format: date-time
210
          description: Date and time when the message was sent.
211
      securitySchemes:
212
        apiKey:
213
          type: apiKey
214
          in: user
215
          description: Provide your API key as the user and leave the password empty.
216
        supportedOauthFlows:
217
          type: oauth2
218
          description: Flows to support OAuth 2.0
219
          flows:
220
            implicit:
221
              authorizationUrl: 'https://authserver.example/auth'
222
              availableScopes:
223
                'streetlights:on': Ability to switch lights on
224
                'streetlights:off': Ability to switch lights off
225
                'streetlights:dim': Ability to dim the lights
226
            password:
227
              tokenUrl: 'https://authserver.example/token'
228
              availableScopes:
229
                'streetlights:on': Ability to switch lights on
230
                'streetlights:off': Ability to switch lights off
231
                'streetlights:dim': Ability to dim the lights
232
            clientCredentials:
233
              tokenUrl: 'https://authserver.example/token'
234
              availableScopes:
235
                'streetlights:on': Ability to switch lights on
236
                'streetlights:off': Ability to switch lights off
237
                'streetlights:dim': Ability to dim the lights
238
            authorizationCode:
239
              authorizationUrl: 'https://authserver.example/auth'
240
              tokenUrl: 'https://authserver.example/token'
241
              refreshUrl: 'https://authserver.example/refresh'
242
              availableScopes:
243
                'streetlights:on': Ability to switch lights on
244
                'streetlights:off': Ability to switch lights off
245
                'streetlights:dim': Ability to dim the lights
246
        openIdConnectWellKnown:
247
          type: openIdConnect
248
          openIdConnectUrl: 'https://authserver.example/.well-known'
249
      parameters:
250
        streetlightId:
251
          description: The ID of the streetlight.
252
      messageTraits:
253
        commonHeaders:
254
          headers:
255
            type: object
256
            properties:
257
              my-app-header:
258
                type: integer
259
                minimum: 0
260
                maximum: 100
261
      operationTraits:
262
        mqtt:
263
          bindings:
264
            mqtt:
265
              qos: 1
266