swagger: Add DataProviderCapabilities to swagger documentation #143
Conversation
bhufmann
force-pushed
the
dp-capabilities
branch
from
6ca4880 to
ba570ff
Compare
| @@ -64,4 +64,11 @@ enum ProviderType { | |||
| */ | |||
| @Schema(required = false, description = "Optional input configuration used to create this derived data provider.") | |||
| Configuration getConfiguration(); | |||
|
|
|||
| /** | |||
| * @return option output capabilities. | |||
| /** | ||
| * @return The name. | ||
| */ | ||
| @JsonProperty("canCreate") |
There was a problem hiding this comment.
Should each capabilities parameter be independently optional (required=false) or only the parent 'capabilities'?
Or none? I'm not sure what is the intended outcome, the ADR did not have any optional in the javascript example. In the Java code (IDataProviderDescriptor) the capabilities field is not nullable.
There was a problem hiding this comment.
Not sure if we should make each one optional. I guess it could save some bytes over the TSP. However, on the client side of the TSP, we would have to handle if fields are not there. Either way, let me know what you prefer. It will affect the related PRs (tsp-typescript-client/tsp-python-client).
BTW, the class DataProviderDescriptorSerializer determines if the capabilities are serialized or not. IDataProviderDescriptor is the Trace Compass internal implementation/API.
There was a problem hiding this comment.
Ok, I think we agree to make each subfield optional. It's required=false by default so nothing to change in this file.
| /** | ||
| * @return The name. | ||
| */ | ||
| @JsonProperty("canCreate") |
There was a problem hiding this comment.
Ok, I think we agree to make each subfield optional. It's required=false by default so nothing to change in this file.
| /** | ||
| * @return option output capabilities. | ||
| */ | ||
| @Schema(required = false, description = "Optional output capabilities, such as \"canCreate\" and \"canDelete\".") |
There was a problem hiding this comment.
The required option is false by default, so we can probably omit it everywhere that it's set to false (or leave it to be explicit?).
But it should be added when required = true, I believe in this file it should be added to the fields id, name, description, type. This is how it's currently implemented in tsp-typescript-client.
There was a problem hiding this comment.
I will update the description to make sure that they are optional and what is supposed to happen when omitted. I won't fix the other fields that should have required=true because it should be in a separate PR. I noticed more data structures that need fixing.
bhufmann
force-pushed
the
dp-capabilities
branch
from
ba570ff to
b2e38b4
Compare
| /** | ||
| * @return optional output capabilities. | ||
| */ | ||
| @Schema(description = "Optional output capabilities, such as \"canCreate\" and \"canDelete\". If omitted, all capabilites are false.") |
bhufmann
force-pushed
the
dp-capabilities
branch
from
b2e38b4 to
1f583e3
Compare
| public interface OutputCapabilities { | ||
|
|
||
| /** | ||
| * @return The name. |
| boolean canCreate(); | ||
|
|
||
| /** | ||
| * @return The ID. |
Signed-off-by: Bernd Hufmann <[email protected]>
bhufmann
force-pushed
the
dp-capabilities
branch
from
1f583e3 to
ce19b4b
Compare
bhufmann
merged commit 00a007b
into
eclipse-tracecompass-incubator:master
What it does
This PR adds the DataProviderCapabilities API to the swagger documentation.
See ADR: eclipse-cdt-cloud/theia-trace-extension#1158
How to test
Run trace-server and create the API documentation as described here https://github.com/eclipse-cdt-cloud/trace-server-protocol?tab=readme-ov-file#generate-the-api.
Follow-ups
N/A
Review checklist
Signed-off-by: Bernd Hufmann [email protected]