swagger-api / swagger-api/swagger-client

Form request body with array value does not use default 'explode' property

Open
#2,713 1 comment 14 reactions 0 assignees View on GitHub

Nobody has claimed this yet.

Dominant language
JavaScript
Stars
2.7k
Forks
765
Avg merge
1d 1h
Merged PRs (30d)
6

Description

Q&A (please complete the following information)
  • OS: macOS
  • Environment: Chrome
  • Method of installation: none - using https://editor.swagger.io/
  • Swagger-Client version: 3.25.5
  • Swagger/OpenAPI version: OpenAPI 3.0
Content & configuration

Plug in the below yaml into https://editor.swagger.io/

Swagger/OpenAPI definition:

openapi: 3.0.2
info:
  title: Tempus Docs
  version: 0.1.0
paths:
  /withlistparams:
    post:
      summary: With List Params
      operationId: with_list_params_withlistparams_post
      requestBody:
        content:
          application/x-www-form-urlencoded:
            schema:
              $ref: '#/components/schemas/Body_with_list_params_withlistparams_post'
        required: true
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
components:
  schemas:
    Body_with_list_params_withlistparams_post:
      title: Body_with_list_params_withlistparams_post
      required:
      - vals
      type: object
      properties:
        vals:
          title: Vals
          type: array
          items:
            type: string

Swagger-Client usage:
N/A

Describe the bug you're encountering

When I go to 'Try it Out' on the '/withlistresponse' operation and fill out items for the vals array, I get the default serialization behavior of csv in the request:

image

I believe that this is a misinterpretation of the default value of the style keyword within the encoding for a request body specified in the OpenAPI spec.

There appears to be no default set for the style field in swagger-ui (most recently this would have been from #https://github.com/swagger-api/swagger-js/pull/1500). The default value of style should be form, relevant part from the linked spec (emphasis mine):

Describes how a specific property value will be serialized depending on its type. See Parameter Object for details on the style property. The behavior follows the same values as query parameters, including default values

If you look at the parameterStyle property, the spec states:

Default values (based on value of in): for query - form;

If I take my example above and modify it slightly, you can see then that these 2 yaml snippets should be the exact same behavior:

Original:

      requestBody:
        content:
          application/x-www-form-urlencoded:
            schema:
              $ref: '#/components/schemas/Body_with_list_params_withlistparams_post'
        required: true

Output is CSV:

image

style: form, output is effectively explode: true with repeated parameters:

      requestBody:
        content:
          application/x-www-form-urlencoded:
            schema:
              $ref: '#/components/schemas/Body_with_list_params_withlistparams_post'
            encoding:
              vals:
                style: form
        required: true
image
To reproduce...

Steps to reproduce the behavior:

  1. Specify a form request body with a schema that contains an array field
  2. Go to 'Try it Out'
  3. Populate the array field with some values
  4. Hit 'Execute'
  5. See the request uses a csv for the array value (effectively explode: false in the encoding)
Expected behavior

The defaults from the OpenAPI specification are respected

Screenshots

Given above

Additional context or thoughts

Contributor guide

Open the contributing guide

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. Open a pull request that references the issue number.

Research direction

Reproduce the issue in https://editor.swagger.io/ using the provided OpenAPI 3.0 YAML and the Try it Out flow. Start by tracing the form request-body encoding and compare the omitted style with the explicit style: form example. Done means the default serialization follows the OpenAPI defaults rather than sending the array as CSV.

Written by the indexing model from the issue text.

Assessment

Tech stack
javascript
Domain
api
Issue type
Bug
Difficulty
3/5
Estimated time
1-2 days
Activity status
Stale
Clarity
Clearly specified
Newbie friendliness
48/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.