Skip to content

feat: add explode() annotation for OpenAPI 3.x parameters#2135

Open
curiosity-the-rover wants to merge 1 commit intoswaggo:v2from
curiosity-the-rover:feature/explode-annotation
Open

feat: add explode() annotation for OpenAPI 3.x parameters#2135
curiosity-the-rover wants to merge 1 commit intoswaggo:v2from
curiosity-the-rover:feature/explode-annotation

Conversation

@curiosity-the-rover
Copy link
Copy Markdown

Summary

Add support for the explode() annotation to explicitly set the explode property on query/path/header parameters in OpenAPI 3.x.

Closes #2134

Usage

// @Param ids query []string true "ID List" explode(false)
// @Param tags query []string true "Tag List" explode(true)

This allows users to control whether array/object parameters are serialized as:

  • explode(true): ?ids=a&ids=b&ids=c (repeated params, default for form style)
  • explode(false): ?ids=a,b,c (comma-separated)

Changes

  • operation.go: Add explodeTag constant and regex pattern
  • operationv3.go: Add setExplodeParamV3 function and case in switch
  • operationv3_test.go: Add tests for explode(true/false/invalid)

Generated Output

parameters:
  - in: query
    name: ids
    schema:
      type: array
      items:
        type: string
    explode: false  # or true

Testing

All existing tests pass, plus new tests added for:

  • explode(true) - sets explode to true
  • explode(false) - sets explode to false
  • explode(invalid) - returns appropriate error

Note

Important: For explode: false to be properly serialized in YAML/JSON output, the upstream dependency sv-tools/openapi needs to change Explode from bool to *bool. See: sv-tools/openapi#132

Once that PR is merged, this PR should update the dependency and change the implementation to use *bool.

Add support for the explode() annotation to explicitly set the explode
property on query/path/header parameters in OpenAPI 3.x.

Usage:
  // @param ids query []string true "ID List" explode(false)
  // @param tags query []string true "Tag List" explode(true)

This allows users to control whether array/object parameters are
serialized as:
- explode(true):  ?ids=a&ids=b&ids=c (repeated params)
- explode(false): ?ids=a,b,c (comma-separated)

Changes:
- operation.go: Add explodeTag constant and regex pattern
- operationv3.go: Add setExplodeParamV3 function and case in switch
- operationv3_test.go: Add tests for explode(true/false/invalid)

Closes: swaggo#2134
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant