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

Incorrect example generation for array query parameters #1024

Open
hjhrwerv2423 opened this issue Nov 18, 2024 · 0 comments
Open

Incorrect example generation for array query parameters #1024

hjhrwerv2423 opened this issue Nov 18, 2024 · 0 comments
Labels
bug Something isn't working

Comments

@hjhrwerv2423
Copy link

Current behavior

Plugin generates incorrect curl examples for array query parameters defined with style: form and explode: true. The plugin concatenates the array values into a single parameter with comma-separated values, which does not match the expected API format.

For the simplified OpenAPI file:

openapi: 3.0.0
info:
  title: Simple API
  version: 1.0.0
paths:
  /customers:
    get:
      summary: "Retrieve Customers"
      parameters:
        - name: customerIds[]
          in: query
          required: true
          style: form
          explode: true
          schema:
            type: array
            items:
              type: string
            example:
              - "cust789"
              - "cust123"
      responses:
        '200':
          description: OK

The plugin generates the following incorrect curl example:

curl -X GET 'https://api.example.com/customers?customerIds[]=cust789,cust123'

This example combines the array values into a single parameter customerIds[]=cust789,cust123, which does not work with the API.

Possible solution

Modify the plugin to correctly handle array query parameters with style: form and explode: true by generating separate parameters for each array item. The correct curl example should look like:

curl -X GET 'https://api.example.com/customers?customerIds%5B%5D=cust789&customerIds%5B%5D=cust123'

Steps to reproduce

  1. Install docusaurus-plugin-openapi-docs version ^4.2.0.
  2. Create an OpenAPI file with an array parameter as shown in the example above.
  3. Generate the documentation using the plugin.
  4. Notice that the generated curl example concatenates array values into a single parameter with commas.

How editor.swagger.io generates the curl command

When loading this OpenAPI file into editor.swagger.io, it generates the correct curl example:

curl -X GET "https://api.example.com/customers?customerIds%5B%5D=cust789&customerIds%5B%5D=cust123" -H "accept: application/json"

Editor.swagger.io correctly encodes each array item as a separate query parameter, using customerIds%5B%5D=cust789 and customerIds%5B%5D=cust123, which aligns with the OpenAPI specification and the expected API behavior.

Your Environment

  • Version used: docusaurus-plugin-openapi-docs ^4.2.0
  • Environment name and version: Node.js v14.x
  • Operating System and version: Windows 10
  • Link to your project: Private project; the issue can be reproduced using the provided OpenAPI file.
@hjhrwerv2423 hjhrwerv2423 added the bug Something isn't working label Nov 18, 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
Projects
None yet
Development

No branches or pull requests

1 participant