OpenAPITools / OpenAPITools/openapi-generator
[BUG][PYTHON] Boolean parameter examples rendered as lowercase 'true'/'false' instead of capitalized 'True'/'False' in generated Python docs (v7.16.0)
Nobody has claimed this yet.
- Dominant language
- Java
- Stars
- 26.8k
- Forks
- 7.7k
- PR merge metrics
- PR metrics pending
Description
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?
Description
When generating a Python client with OpenAPI Generator v7.16.0 (Docker image: openapitools/openapi-generator-cli:v7.16.0), if a boolean query parameter has an explicit example: true or example: false in the OpenAPI spec, the generated Python documentation (e.g. docs/DefaultApi.md) renders the example as lowercase true or false instead of Python's capitalized True or False.
This results in invalid Python code in the generated documentation and breaks copy-paste for users. Removing the explicit example: field results in correct output (capitalized True/False).
Minimal OpenAPI Spec to Reproduce
Filename: test-boolean-lowercase-issue.yaml
openapi: 3.0.0
info:
title: Minimal Example - Boolean Lowercase in Python Docs
version: 1.0.0
description: |
This minimal spec reproduces the issue where OpenAPI Generator v7.16.0
with custom templates generates Python documentation examples with lowercase
boolean values (false/true) instead of Python's capitalized booleans (False/True)
when an explicit example is provided in the spec.
servers:
- url: https://api.example.com
paths:
/items:
get:
summary: List items
operationId: listItems
parameters:
- name: include_deleted
in: query
required: false
schema:
type: boolean
description: Include deleted items in results
example: false
- name: active_only
in: query
required: false
schema:
type: boolean
description: Show only active items
example: true
responses:
'200':
description: Success
content:
application/json:
schema:
type: object
properties:
count:
type: integer
Generation Command
docker run --rm \
-v "$(pwd)/test-boolean-lowercase-issue.yaml:/local/test.yaml" \
-v "$(pwd)/out:/out" \
openapitools/openapi-generator-cli:v7.16.0 generate \
-i /local/test.yaml \
-g python \
-o /out \
--package-name test_client
Actual Generated Output (docs/DefaultApi.md)
include_deleted = false # bool | Include deleted items in results (optional)
active_only = true # bool | Show only active items (optional)
Expected Output
include_deleted = False # bool | Include deleted items in results (optional)
active_only = True # bool | Show only active items (optional)
Problem
- OpenAPI spec uses
example: false/example: true(valid YAML boolean syntax) - Generator outputs these literally as
false/truein Python code examples - Python requires capitalized
False/True— the generated example code is not valid Python
Workaround
Remove explicit example: values from boolean parameters. Without explicit examples, the generator correctly uses Python's False/True in documentation examples:
parameters:
- name: include_deleted
in: query
schema:
type: boolean
# No explicit example - generator will use correct Python booleans
Suggest a Fix
The generator should render Python boolean examples as True/False in all generated Python documentation and example code, regardless of whether an explicit YAML boolean is provided as an example in the spec.
This is a bug in OpenAPI Generator v7.16.0's default Python templates.
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
Reproduce the issue with test-boolean-lowercase-issue.yaml using the documented Docker generation command, then inspect the default Python templates responsible for docs/DefaultApi.md. Verify how explicit boolean examples are rendered and add coverage for both true and false; done means generated Python examples use True and False without affecting other values.
Written by the indexing model from the issue text.
Assessment
- Tech stack
- python
- Domain
- documentation, tooling
- Issue type
- Bug
- Difficulty
- 3/5
- Estimated time
- 1-2 days
- Activity status
- Stale
- Clarity
- Mostly clear
- Newbie friendliness
- 48/100