Skip to content
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

The sample code is wrong when using in query parameters with a list of values #909

Open
JaimeOVasconcelos opened this issue Aug 6, 2024 · 1 comment
Labels
bug Something isn't working roadmap Features or bug fixes planned for future release

Comments

@JaimeOVasconcelos
Copy link

JaimeOVasconcelos commented Aug 6, 2024

Describe the bug

The generated code in curl, Python, etc. is not well generated when we have query parameters with a list of values.
The query parameters in the sample code have the list of values separated by commas (",") and should be exploded instead, i.e., repeat the query parameter for each value separated by an "&".
This behavior is defined by the explode OpenAPI property (that defaults to true), which seems to be being ignored.
Even when we force explode to true, it is ignored.
See this example in the OpenAPI spec (you can download it with the Export button at https://developers.probely.com/api/reference/probely-developer-documentation):

image

See more about the explodeproperty at https://swagger.io/docs/specification/serialization/#query

Expected behavior

In the endpoint https://developers.probely.com/api/reference/api-users-list, when adding values for query parameters exclude and exclude_target like this:

Screenshot 2024-08-06 at 17 38 12

Screenshot 2024-08-06 at 17 38 36

The generated curl should be:

curl -L -X GET 'https://api.probely.com/api-users/?exclude=field1&exclude=field2&exclude_target=t1&exclude_target=t2' \
-H 'Accept: application/json' \
-H 'Authorization: JWT <YOUR_API_TOKEN>'

Current behavior

Currently, the generated curl is wrong with the values of the query params exclude and exclude_targetseparated by commas (","):

curl -L -X GET 'https://api.probely.com/api-users/?exclude=field1,field2&exclude_target=t1,t2' \
-H 'Accept: application/json' \
-H 'Authorization: JWT <YOUR_API_TOKEN>'

Possible solution

Consider the explode property of the OpenAPI to generate the sample code.

If explode is not defined or is true the query parameters in the sample code should be repeated for each value that is inserted and separated by "&".
If explode is false the values of the query parameter in the sample code should be separated by a comma (",")

Steps to reproduce

  1. Go to https://developers.probely.com/api/reference/api-users-list
  2. At the right hand side, in the REQUEST section, click on Show optional parameters
  3. Add "field 1" and "field2" to the exclude query parameter
  4. Add "t1" and "t2" to the exclude_targetquery parameter
  5. Check the generated sample code in curl that is generated with query parameters separated by commas

Screenshots

image

Context

This provides a bad user experience for people trying to get the sample code to use the API endpoint since it will not work, and it's difficult to understand why.

Your Environment

  • Version used: docusaurus: 2.4.3, docusaurus-plugin-openapi-docs: 2.1.0
@JaimeOVasconcelos JaimeOVasconcelos added the bug Something isn't working label Aug 6, 2024
@sserrata
Copy link
Member

sserrata commented Aug 6, 2024

Related to #750

@sserrata sserrata added the roadmap Features or bug fixes planned for future release label Aug 6, 2024
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
bug Something isn't working roadmap Features or bug fixes planned for future release
Projects
None yet
Development

No branches or pull requests

2 participants