elements

elements copied to clipboard

User story.

As a user who has designed APIs with query string arrays and/or exploding on comma, my user can see clean URLs instead of a technically probably valid but ugly encoded version.

Is your feature request related to a problem?

It's hard to tell what this URL means due to all the URL encoded parameter names and values.

curl --request GET \
  --url 'https://example.com/foos?status%5B%5D=available&client_ids%5B%5D=1%2C2%2C3' \
  --header 'Content-Type: application/json'

Describe the solution you'd like

• If the user has provided allowReserved: true for a parameter, let's not encode the value.
• We should see if we can avoid encoding [] in the query params ever, regardless of that switch.
• This is OAS3 only, OAS2 does not have allowReserved: true

Spec link: http://spec.openapis.org/oas/v3.0.3.html#fixed-fields-9

So the output would be:

curl --request GET \
  --url 'https://example.com/foos?status[]=available&client_ids[]=1,2,3' \
  --header 'Content-Type: application/json'

You can use this OpenAPI to get a realistic sample.

openapi: 3.0.1
info:
  title: Query Param Arrays
  description: Query Param Arrays
  version: 1.0.0
servers:
- url: https://example.com
paths:
  /foos:
    get:
      summary: Finds Pets by status
      description: Multiple status values can be provided with multiple status[] params.
      operationId: getFoos
      parameters:
      - name: "status[]"
        in: query
        description: Status values that need to be considered for filter
        required: true
        schema:
          type: string
          default: available
          enum:
          - available
          - pending
          - sold
      - name: 'client_ids[]'
        in: query
        schema:
          type: array
          uniqueItems: true
          items: 
            type: integer
        explode: true
        style: form
        allowReserved: true
      responses:
        200:
          description: successful operation     

Any updates in issue?

Having this enabled would be great and is one of the major things holding back our adoption of this for our api documentation.

We have a lot of endpoints that expect a query string ?expand[]=item&expand[]=item2 and PHP parses that into an array [ 'item1', 'item2' ]. By naming the parameter expand[] and keeping the default explode: true and style: form should generate the query string shown.

However, there is no way to generate this using the editor. In our case, the expand[] parameter is an array of enum, so a multiple list select (similar to what Swagger UI) would be great to generate that string.

@Icexist I bet it would help the team a lot if you could make a small OpenAPI file that described this entire situation? That would be useful for a test case, which is often 80% of the work for some more complex issues.

openapi: 3.0.1
info:
  title: Query Param Arrays
  description: Query Param Arrays
  version: 1.0.0
servers:
- url: https://example.com
paths:
  /foos:
    get:
      summary: Finds Pets by status
      description: Use the expand parameter to add additional fields.
      parameters:
      - name: "expand[]"
        in: query
        description: Options to pull additional fields
        style: form
        explode: true
        schema:
          type: array
          items:
            type: string
            enum:
            - available
            - pending
            - sold
      responses:
        '200':
          description: OK

HTTP Request:

GET https://example.com/foos?expand[]=available&expand[]=pending

PHP interpreted:

$expand = ['available','pending'];

When used in a Laravel Lumen validation:

// Route /foos
public function handleFoos(Request $request)
{
    $this->validate($request,[
        'expand'    => 'array',
        'expand.*'  => [Rule::in(['available','pending','sold'])],
    ]);
}

Swagger UI ( from editor.swagger.io ):

Hey, any update on this?

As a Laravel user we use, something like filter[userId]=1.

The filter columns should be enums, so that there is only these allowed.

Documenting something like filter[firstName]=Max and so on would be really great.

Is there a way to document this in Stoplight Studio? If so... How?

Is this allowed or is it a bad practice?

Additional info, my use case is to support something like comma separated strings as param:

/pet/findByTags?tags=string,string

Version: OpenAPI 3.1

Does Stoplight 'Try It' support allowReserved: true yet?

        "parameters": [
          {
            "name": "tags",
            "in": "query",
            "description": "Tags to filter by",
            "required": false,
            "explode": false,
            "style": "form",
            "allowReserved": true,
            "schema": {
              "type": "array",
              "items": {
                "type": "string"
              }
            }
          },
          ...