Bug: Description not set for UUID based path parameters in OpenAPI

[Alc-Alc]

Description

The value set in Parameter(description="UUID ID") is not used for the actual description in the OpenAPI schema if the path parameter is of type UUID. I did some digging and found out this is due to the presence of the following code.

litestar/litestar/_openapi/schema_generation/schema.py

Lines 525 to 532 in 4480918

	# we only want to transfer values from the `KwargDefinition` to `Schema` if the schema object
	# doesn't already have a value for that property. For example, if a field is a constrained date,
	# by this point, we have already set the `exclusive_minimum` and/or `exclusive_maximum` fields
	# to floating point timestamp values on the schema object. However, the original `date` objects
	# that define those constraints on `KwargDefinition` are still `date` objects. We don't want to
	# overwrite them here.
	if getattr(schema, schema_key, None) is None:
	setattr(schema, schema_key, value)

Since description for UUID is already set

litestar/litestar/_openapi/schema_generation/schema.py

Line 120 in 4480918

UUID: Schema(type=OpenAPIType.STRING, format=OpenAPIFormat.UUID, description="Any UUID string"),

the code above makes it so that description from the user defined Parameter is not set again.

Proposed Fix 1 (Breaking / debatably breaking?)

Remove "description" in

litestar/litestar/_openapi/schema_generation/schema.py

Line 120 in 4480918

UUID: Schema(type=OpenAPIType.STRING, format=OpenAPIFormat.UUID, description="Any UUID string"),

such that it appears like so

UUID: Schema(type=OpenAPIType.STRING, format=OpenAPIFormat.UUID)

Proposed Fix 2 (Special Casing until next major release then replace with Proposed Fix 1)

Change

litestar/litestar/_openapi/schema_generation/schema.py

Line 531 in 4480918

if getattr(schema, schema_key, None) is None:

such that it appears like so

if schema_key == "description" or getattr(schema, schema_key, None) is None:

@peterschutt suggested special casing with comments explaining the behavior would be ideal. Thoughts?

URL to code causing the issue

No response

MCVE

from uuid import UUID
from typing_extensions import Annotated
from litestar.params import Parameter
from litestar import get
from litestar.testing import create_test_client

@get("str/{id:str}")
async def str_path(id: Annotated[str, Parameter(description="String ID")]) -> str:
    return id

@get("uuid/{id:uuid}")
async def uuid_path(id: Annotated[UUID, Parameter(description="UUID ID")]) -> UUID:
    return id

with create_test_client([str_path, uuid_path]) as client:
    # correct, currently passes, should pass
    assert client.app.openapi_schema.paths["/str/{id}"].get.parameters[0].description == "String ID"

    # wrong, currently passes, should fail
    assert client.app.openapi_schema.paths["/uuid/{id}"].get.parameters[0].description == "Any UUID string"

    # expected, currently fails, should pass
    assert client.app.openapi_schema.paths["/uuid/{id}"].get.parameters[0].description == "UUID ID"

Steps to reproduce

1. Save as "mcve.py"
2. Run `python mcve.py`
3. Second assert that currently passes, should fail.
4. Third assert that currently fails, should pass.

Screenshots

"![SCREENSHOT_DESCRIPTION](SCREENSHOT_LINK.png)"

Logs

No response

Litestar Version

cc45c11 (main as of issue creation)

Platform

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

---

Note

While we are open for sponsoring on GitHub Sponsors and
OpenCollective, we also utilize Polar.sh to engage in pledge-based sponsorship.

Check out all issues funded or available for funding on our Polar.sh dashboard

• If you would like to see an issue prioritized, make a pledge towards it!
• We receive the pledge once the issue is completed & verified
• This, along with engagement in the community, helps us know which features are a priority to our users.

[peterschutt]

Proposed Fix 1 (Breaking / debatably breaking?)

If we treat this as a bug and include the fix in a patch release, removing the default description will cause schema generation to change behavior between patch releases - this is why I'm in favor of option 2.

[provinzkraut]

@Alc-Alc would you want to go ahead and implement a fix for this?

[github-actions]

This issue has been closed in #3118. The change will be included in the upcoming patch release.

[github-actions]

A fix for this issue has been released in v2.6.2