chore(26181): OpenAPI specs for the bi-directionality features #564
Conversation
vanch3d
requested review from
sfrehse,
codepitbull,
AcidSepp,
Florian-Limpoeck and
DC2-DanielKrueger
|
@vanch3d, it's great that you come up with the proposal. Do you have any idea how we can better review that? The view in GH is not optimal to comment :-) |
| tags: | ||
| - Domain | ||
|
|
||
| /api/v1/management/client/topic-samples: |
There was a problem hiding this comment.
Why is this needed?
There was a problem hiding this comment.
why is this path under the root '/client' but topics are under the root '/domain' ?
vanch3d
force-pushed
the
chore/26181/bi-directionality-openAPI
branch
from
6c0238f
to
b909d6f
Compare
- fix response of domain/tags/schema - create TagSchemaList - rename DeviceDataPoint into DomainTagAddress - add additionalProperties to schema
|
Big supporter of this, as this gives not only more insights to the Frontend Engineers but also later customer that consume potentially the API. This would allow the customers to react to errors and build more recoverable services.
Agree with @sfrehse here it's really hard to get into. |
| summary: Get data schemas | ||
| tags: | ||
| - Domain | ||
| /api/v1/management/domain/topics: |
There was a problem hiding this comment.
is this only for publish 'topics' or also for subscribe 'topicFilters' ?
| application/json: | ||
| example: | ||
| items: | ||
| - client1/topic1 |
There was a problem hiding this comment.
i dont understand the examples. wouldnt it be something like:
{
"clientId" : "my-fancy-client",
"topic": "a/b/c"
}
| description: Get a sample of MQTT topics published by clients connected to the Edge broker over a period of time | ||
| operationId: get-client-topics | ||
| parameters: | ||
| - description: The time limit for the observation. |
There was a problem hiding this comment.
in seconds or milliseconds?
| schema: | ||
| type: integer | ||
| minimum: 500 | ||
| default: 1000 |
There was a problem hiding this comment.
in millis, the default seems a bit short, there can be nothing. in seconds its far to long, we cant cache topic data for so long
See https://hivemq.kanbanize.com/ctrl_board/57/cards/26181/details/
This PR is part of the bi-directional epic and adds a proposal for the expected OpenAPI specs of the new features
The changes are as follows:
WRITEadded to the capability of the protocol adapterstagson devices (through their protocol adapter)Clientcategory of services to handle requests for MQTT client filtersDomaincategory of services to handle requests for domain tags and topic schemaFor the definition and scope of the entities, refer to the
bi-directionalityMIRO board: https://miro.com/app/board/uXjVKydZ7vo=/#Problem Details
The PR also corrects the definition of the
ProblemDetailsspecification, RFC9457 (formerly RFC7807).The
OpenAPIspecs are copied from the official SmartBear registry, https://github.com/SmartBear-DevRel/problems-registry. They are embedded in the specs but, ideally, they should be used as a reference to an external file. The specs have been added as a separateOpenAPIspecs for reference.Out-of-scope
configproperty. A custom endpoint could be created to export the mappings; it will be tried in a further ticket.Design
For clarity, a version of the specs containing only the changes can be found below, to be used in Swagger or IntelliJ.