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)

Open
#22,240 0 comments 0 reactions 0 assignees View on GitHub

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/true in 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

Open the contributing guide

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. 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

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.