OpenAPITools / OpenAPITools/openapi-generator
[BUG][PYTHON] Complex object query parameters with style: form and explode: true
Nobody has claimed this yet.
- Dominant language
- Java
- Stars
- 26.8k
- Forks
- 7.7k
- PR merge metrics
- PR metrics pending
Description
[BUG][PYTHON] Complex object query parameters with style: form and explode: true serialize as JSON instead of form data
Bug Report Checklist
- Have you provided a full/minimal spec to reproduce the issue?
- Have you validated the input using an OpenAPI validator?
- Have you tested with the latest master to confirm the issue still exists?
- Have you searched for related issues/PRs?
- What's the actual output vs expected output?
- [Optional] Sponsorship to speed up the bug fix or feature request
Description
When using a complex object as a query parameter with style: form and explode: true, the Python OpenAPI generator serializes the object as a URL-encoded JSON string instead of expanding it into individual form parameters.
This makes the API calls incompatible with servers expecting proper form-encoded query parameters.
openapi-generator version
7.14.0
OpenAPI declaration file content or url
# Minimal reproduction case
openapi: 3.0.3
info:
title: Test API
version: 1.0.0
paths:
/test-items:
get:
parameters:
- in: query
name: filters
schema:
$ref: "#/components/schemas/TestFilters"
style: form
explode: true
responses:
'200':
description: Success
content:
application/json:
schema:
type: object
components:
schemas:
TestFilters:
type: object
properties:
ids:
type: array
items:
type: string
description: List of IDs to filter by
example: ["123", "456", "789"]
statuses:
type: array
items:
type: string
description: List of statuses
example: ["DRAFT", "COMPLETED"]
createdAtFrom:
type: string
format: date-time
description: Creation date-time range start
Generation Details
Generator configuration:
{
"generator-cli": {
"version": "7.14.0"
},
"generatorName": "python",
"inputSpec": "openapi.yaml",
"outputDir": ".",
"additionalProperties": {
"packageName": "test_api_client",
"projectName": "Test API Client",
"packageVersion": "1.0.0",
"packageDescription": "OpenAPI client",
"generateSourceCodeOnly": true
}
}
CLI command:
openapi-generator-cli generate -c openapitools.json
Steps to reproduce
- Create an OpenAPI spec with a complex object query parameter using
style: formandexplode: true - Generate Python client using openapi-generator v7.14.0
- Use the generated client to make an API call with the complex object parameter
- Observe the actual HTTP request URL
Actual vs Expected Output
Actual URL generated:
?filters=%7B%22ids%22%3A%5B%22test-123%22%5D%2C%22statuses%22%3A%5B%22DRAFT%22%5D%7D
(URL-encoded JSON: {"ids":["test-123"],"statuses":["DRAFT"]})
Expected URL with style: form and explode: true:
?ids=test-123&statuses=DRAFT
Code example that demonstrates the issue:
from test_api_client import TestItemsApi, TestFilters
filters = TestFilters(
ids=["test-123"],
statuses=["DRAFT"]
)
# This generates the wrong URL format
api.get_test_items(filters=filters)
Suggest a fix
The Python generator should properly handle style: form and explode: true for complex objects by either expanding the object into individual query parameters or serializing the object to form data instead of JSON.
Something like
if hasattr(filters, 'to_dict'):
filters_dict = filters.to_dict()
for key, value in filters_dict.items():
if value is not None:
if isinstance(value, list):
for item in value:
if hasattr(item, 'value'): # Handle enums
_query_params.append((key, item.value))
else:
_query_params.append((key, item))
else:
if hasattr(value, 'value'): # Handle enums
_query_params.append((key, value.value))
else:
_query_params.append((key, value))
else:
_query_params.append(('filters', filters))
Contributor guide
First steps
- Read the whole issue, then the project's contributing guide.
- Comment on the issue to say you are picking it up — it saves two people doing the same work.
- Fork the repository and make your change on a branch.
- Open a pull request that references the issue number.
Research direction
Start by generating the Python client from the minimal OpenAPI 3.0.3 declaration in the issue, then inspect the generated client's query-parameter serialization path. Reproduce the request with filters containing ids and statuses; done means form-style, exploded parameters produce separate query values such as ?ids=test-123&statuses=DRAFT rather than URL-encoded JSON.
Written by the indexing model from the issue text.
Assessment
- Tech stack
- openapi, python
- Domain
- api, tooling
- Issue type
- Bug
- Difficulty
- 4/5
- Estimated time
- 3-5 days
- Activity status
- Stale
- Clarity
- Mostly clear
- Newbie friendliness
- 45/100