#3057·litestar

Enhancement: Only generate example once when `Parameter(examples=[...])` is specified for path arg and its schema

Author: mtvxCreated Feb 1, 2024Updated Sep 11, 2026
LabelsEnhancementHelp Wanted :sos:area/openapi

Description

Explained below.

MCVE

python
import json

from litestar import Litestar, post
from litestar.openapi.spec import Example
from litestar.params import Parameter


@post("/{path_arg:str}")
def endpoint(
    path_arg: str = Parameter(examples=[Example(value="EXAMPLE_VALUE")]),
) -> None:
    pass

app = Litestar(route_handlers=[endpoint])

print(json.dumps(app.openapi_schema.to_schema(), indent=4))

The generated schema contains:

json
                    {
                        "name": "path_arg",
                        "in": "path",
                        "schema": {
                            "type": "string",
                            "examples": {  <------- HERE
                                "path_arg-example-1": {
                                    "value": "EXAMPLE_VALUE"
                                }
                            }
                        },
                        "required": true,
                        "deprecated": false,
                        "allowEmptyValue": false,
                        "allowReserved": false,
                        "examples": { <------- HERE
                            "path_arg-example-1": {
                                "value": "EXAMPLE_VALUE"
                            }
                        }
                    }

I would expect one occurrence is sufficient. The example was given for/as OpenAPI path parameter (via Parameter) so the latter is correct, and the JSON schema example (former one) can be dropped.

Steps to reproduce

bash
1. `python app.py`
2. See the generated schema

Screenshots

No response

Logs

No response

Litestar Version

2.5.1

Platform

  • Linux
  • Mac
  • Windows
  • Other (Please specify in the description above)