-
Task
-
Resolution: Unresolved
-
L3 - Default
-
None
-
None
-
None
Current OpenAPI documentation:
Example from the GetDeployments endpoint:
{
"name": "tenantIdIn",
"in": "query",
"schema":
{ "type": "string" },
"description": "Filter by a comma-separated list of tenant ids. A deployment must have one of the given tenant ids."
}
Acceptance Criteria (Required on creation):
- Query parameters that are comma-separated string list of items are be documented via styles so that list/array as type is used for more easy/intuitive input of the request parameters.
- test the requests are valid for the REST API via Swagger UI (encoding) and generated clients (List<String>)
Hints (Optional):
- 3.0 spec provides the explode options so you can serialize from a list<> into a query param: https://swagger.io/docs/specification/serialization/
- OpenAPI spec: https://github.com/OAI/OpenAPI-Specification/blob/3.0.2/versions/3.0.2.md#style-values
- style: form, explode: false from the example table
- style: form, explode: false from the example table
This is the controller panel for Smart Panels app
[CAM-13502] In OpenAPI, comma-separated list query params are documented as lists
Hi StephenOTT,
thanks for this remark with the comma-separated string parameters.
I agree that it makes sense to adjust this in our OpenAPI documentation.
Regarding the type of this ticket, I will transform it into a Task rather than a Bug Report. As far as we can tell, the functionality of the parameters is not affected by the current type - i.e., you can still put in a comma-separated list of string elements that will be correctly consumed and split up. I therefore consider this an improvement task with the current OpenAPI documentation that provides more clarity and ease-of-use but does not bring along more features.
As for prioritization, we will decide on when to fit this into the roadmap as this requires quite some manual effort to adjust on the whole API. You can follow this ticket as usual to get updates on that.
We are of course happy to accept PRs in case you would like to get going with this already to speed up the process.
Please correct me if any of the prior statements are wrong or don't make sense.
Best,
Tobias
Hi StephenOTT,
thanks again for bringing this topic to our attention. We agree that this would improve the ease-of-use of such list parameters. However, due to other commitments and priorities we will not add this to our roadmap for now.
That being said, we are of course happy to accept PRs in case you would like to move forward with this yourself. Any help that you need for that, let us know!
Best,
Tobias
This ticket was migrated to github: https://github.com/camunda/camunda-bpm-platform/issues/2625. Please use this link for any future references and continue any discussion there.
StephenOTT, thank you for raising this ticket. I was able to confirm that the styles can be used to adjust the input of query parameters according to our needs.
I will send the ticket for a decision.