Skip to content

Feature request: Support for 'explode' parameter in OpenAPI 3.x array query parameters #2134

@curiosity-the-rover

Description

@curiosity-the-rover

Description

When generating OpenAPI 3.x specs with -v3.1 flag, there's no way to specify explode: false for array query parameters.

Current Behavior

Using collectionFormat(csv) annotation:

// @Param ids query []string false "Filter by IDs" collectionFormat(csv)

Generates:

- name: ids
  in: query
  schema:
    type: array
    items:
      type: string
  style: form

The explode property is missing, which defaults to true per OpenAPI 3.x spec.

Expected Behavior

Ability to generate explode: false for comma-separated array serialization:

- name: ids
  in: query
  schema:
    type: array
    items:
      type: string
  style: form
  explode: false

Proposed Solution

Add support for explode(false) or explode(true) annotation:

// @Param ids query []string false "Filter by IDs" style(form) explode(false)

Or extend collectionFormat to properly map to OpenAPI 3.x:

  • collectionFormat(csv)style: form, explode: false
  • collectionFormat(multi)style: form, explode: true

Use Case

This is needed for API contracts where the frontend expects comma-separated arrays (?ids=a,b,c) instead of repeated parameters (?ids=a&ids=b&ids=c).

Environment

  • swag version: v2.0.0-rc5 (binary reports as v2.0.0)
  • Go version: 1.25.4
  • Using -v3.1 flag for OpenAPI 3.1 generation

Metadata

Metadata

Assignees

No one assigned

    Labels

    No labels
    No labels

    Type

    No type

    Projects

    No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions