fix(open-api): support generic types for OpenAPI schema generation

[guacs]

Pull Request Checklist

• New code has 100% test coverage
• (If applicable) The prose documentation has been updated to reflect the changes introduced by this PR
• (If applicable) The reference documentation has been updated to reflect the changes introduced by this PR
• Pre-Commit Checks were ran and passed
• Tests were ran and passed

Description

• This PR adds support for generating the OpenAPI schema for generic types.

Close Issue(s)

• Fixes Bug: Missing API Schema for generic response type annotations #2383

[guacs]

The reason the generic types were not working was because get_type_hints does not resolve the generic types as seen here. So a helper function was created to get the type hints after resolving for the generic types as much as possible. The relevant tests should make the expected behavior clear.

For the following handlers, the resulting schema will be as follows:

from typing import Generic, TypeVar
from dataclasses import dataclass
from litestar import get, post
from litestar.app import Litestar

T = TypeVar("T")


@dataclass
class Foo(Generic[T]):
    foo: T


@get("/")
async def get_foo() -> Foo[int]:
    return Foo(1)


@get("/no-type")
async def get_foo_no_type() -> Foo:
    return Foo(1)


@post("/generic-type")
async def get_foo_generic(foo: Foo[T]) -> Foo[T]:
    return foo


app = Litestar([get_foo, get_foo_no_type, get_foo_generic])

[guacs]

Generic Pydantic models do not work currently due to this issue. I just realized (as I was typing this :P) a simple workaround for this would be to just get the __parameters__ and __args__ using the pydantic API and then use the _substitute_typevars to get the correct type hints.

I'll add this in along with tests to this PR itself.

[peterschutt]

Sorry, ran out of time to complete my review, but a couple of comments so far. I'll pick up again later. Cheers!

[guacs]

@peterschutt first of all, thank you for such a fantastic analysis!

Yeah so the reason for this is that in _substitute_typevars, the check for whether there are any values for __parameters__ was incorrect. Essentially the substitution should only happen if there are any __parameters__. The current _substitute_typevars implementation should be changed to:

def _substitute_typevars(obj: Any, typevar_map: Mapping[Any, Any]) -> Any:
    params = getattr(obj, "__parameters__", None)

    if params: # this was `if params is None` before but list[str].__parameters__ returns an empty tuple instead
        args = tuple(_substitute_typevars(typevar_map.get(p), typevar_map) for p in params)
        return obj[args]

    ....

This also resolves the issue related to __slots__ being returned in get_type_hints! It doesn't matter even if __slots__ is included in the type hints since the OpenAPI generation will be using the respective APIs to get the field names and then use that to get the annotation from the resolved type hints dictionary we get from get_type_hints_with_generics_resolved.

[peterschutt]

This also resolves the issue related to slots being returned in get_type_hints! It doesn't matter even if slots is included in the type hints since the OpenAPI generation will be using the respective APIs to get the field names and then use that to get the annotation from the resolved type hints dictionary we get from get_type_hints_with_generics_resolved

Oh, of course! Good stuff:)

[peterschutt]

Nice work, thanks!

[sonarcloud]

Kudos, SonarCloud Quality Gate passed!   

0 Bugs
0 Vulnerabilities
0 Security Hotspots
1 Code Smell

95.1% Coverage
0.0% Duplication

[github-actions]

Documentation preview will be available shortly at https://litestar-org.github.io/litestar-docs-preview/2463