-
Notifications
You must be signed in to change notification settings - Fork 23
New issue
Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.
By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.
Already on GitHub? Sign in to your account
chore(26181): OpenAPI specs for the bi-directionality features #564
base: master
Are you sure you want to change the base?
Conversation
@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.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Why is this needed?
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
why is this path under the root '/client' but topics are under the root '/domain' ?
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.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
is this only for publish 'topics' or also for subscribe 'topicFilters' ?
application/json: | ||
example: | ||
items: | ||
- client1/topic1 |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
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.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
in seconds or milliseconds?
schema: | ||
type: integer | ||
minimum: 500 | ||
default: 1000 |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
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:
WRITE
added to the capability of the protocol adapterstags
on devices (through their protocol adapter)Client
category of services to handle requests for MQTT client filtersDomain
category of services to handle requests for domain tags and topic schemaFor the definition and scope of the entities, refer to the
bi-directionality
MIRO board: https://miro.com/app/board/uXjVKydZ7vo=/#Problem Details
The PR also corrects the definition of the
ProblemDetails
specification, RFC9457 (formerly RFC7807).The
OpenAPI
specs 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 separateOpenAPI
specs for reference.Out-of-scope
config
property. 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.