fix: JSON schema examples were OpenAPI formatted

[tuukkamustonen]

Description

The generated examples in JSON schema objects were formatted as:

    "examples": {
      "some-id": {
        "description": "Lorem ipsum",
        "value": "the real beef"
      }
   }

However, above is OpenAPI example format, and must not be used in JSON schema
objects. Schema objects follow different formatting:

    "examples": [
      "the real beef"
   ]

This is explained in
https://medium.com/apis-you-wont-hate/openapi-v3-1-and-json-schema-2019-09-6862cf3db959

Schema objects spec in
https://spec.openapis.org/oas/v3.1.0#schema-object.

OpenAPI example format spec in
https://spec.openapis.org/oas/v3.1.0#example-object. This is referenced at
least from parameters, media types and components.

The technical change here is to define Schema.examples as list[Any] instead
of list[Example]. Examples can and must still be defined as list[Example]
for OpenAPI objects (e.g. Parameter, Body) but for JSON schema examples
the code now internally generates/converts list[Any] format instead.

Extra confusion here comes from the OpenAPI 3.0 vs OpenAPI 3.1 difference.
OpenAPI 3.0 only allowed example (singular) field in schema objects.
OpenAPI 3.1 supports the full JSON schema 2020-12 spec and so examples array
in schema objects.

Both example and examples seem to be supported, though the former is marked
as deprecated in the latest specs.

This can be tested over at https://editor-next.swagger.io by loading up the
OpenAPI 3.1 Pet store example. Then add examples in components.schemas.Pet
using the both ways and see the Swagger UI only render the example once it's
properly formatted (it ignores is otherwise).

Closes

n/a

Partially fixes #2849 (the OpenAPI UIs don't render badly formatted examples in the spec).

[codecov]

Codecov Report

All modified and coverable lines are covered by tests ✅

Project coverage is 98.23%. Comparing base (024dccf) to head (2ea9324).

Additional details and impacted files

@@            Coverage Diff             @@
##             main    #3224      +/-   ##
==========================================
- Coverage   98.24%   98.23%   -0.01%     
==========================================
  Files         320      320              
  Lines       14445    14446       +1     
  Branches     2298     2298              
==========================================
  Hits        14191    14191              
  Misses        113      113              
- Partials      141      142       +1     

☔ View full report in Codecov by Sentry.
📢 Have feedback on the report? Share it here.

[guacs]

@tuukkamustonen thanks for this! This is something I'd noticed and was meaning to fix, but hadn't gotten the time to actually investigate.

[tuukkamustonen]

Let's see if I can be type linters pass... interesting errors...

[provinzkraut]

Is this a regression @guacs? I vaguely remember a PR that fixed a similar (or actually the same) bug?

[guacs]

Is this a regression @guacs? I vaguely remember a PR that fixed a similar (or actually the same) bug?

If I remember correctly, that PR was for the rendering of examples of things like path parameters, query parameters etc. This is for the examples of the schemas we generate.

[tuukkamustonen]

I'm getting these errors even on latest main:

=> Running mypy
tests/e2e/test_pydantic.py:11: error: Function is missing a type annotation  [no-untyped-def]
tests/unit/test_contrib/test_pydantic/test_schema_plugin.py:73: error: Function is missing a type annotation  [no-untyped-def]
tests/unit/test_openapi/test_responses.py:1: error: Cannot find implementation or library stub for module named "litestar.openapi.plugins"  [import-not-found]
tests/unit/test_openapi/test_responses.py:1: note: See https://mypy.readthedocs.io/en/stable/running_mypy.html#missing-imports
tests/unit/test_security/test_security.py:1: error: Cannot find implementation or library stub for module named "litestar.openapi.plugins"  [import-not-found]
Found 4 errors in 4 files (checked 691 source files)

In develop:

=> Running mypy
tests/e2e/test_pydantic.py:11: error: Function is missing a type annotation  [no-untyped-def]
tests/unit/test_contrib/test_pydantic/test_schema_plugin.py:73: error: Function is missing a type annotation  [no-untyped-def]
Found 2 errors in 2 files (checked 697 source files)

[tuukkamustonen]

Worked after rebase on latest main now, okay...

[peterschutt]

Is this a regression @guacs? I vaguely remember a PR that fixed a similar (or actually the same) bug?

I think this #2660 which was a fix for #2272

[peterschutt]

This was the MCVE from #2272:

from typing_extensions import Annotated
from msgspec import Struct, Meta
from litestar import Litestar, post


class TestBody(Struct):
    field1: Annotated[str, Meta(examples=["the answer"])]
    field2: Annotated[int, Meta(examples=[42])]


@post(sync_to_thread=False)
def test(data: TestBody) -> None:
    ...


if __name__ == "__main__":
    import uvicorn
    uvicorn.run(app=Litestar(route_handlers=[test]), port=8080)

If I run that app on main we get:

Which doesn't include the example values for those fields, so either we've had a regression or that wasn't fixed.

Same app on this branch:

So LGTM on that front.

[guacs]

This was the MCVE from #2272:

from typing_extensions import Annotated
from msgspec import Struct, Meta
from litestar import Litestar, post


class TestBody(Struct):
    field1: Annotated[str, Meta(examples=["the answer"])]
    field2: Annotated[int, Meta(examples=[42])]


@post(sync_to_thread=False)
def test(data: TestBody) -> None:
    ...


if __name__ == "__main__":
    import uvicorn
    uvicorn.run(app=Litestar(route_handlers=[test]), port=8080)

If I run that app on main we get:

Which doesn't include the example values for those fields, so either we've had a regression or that wasn't fixed.

Same app on this branch:

So LGTM on that front.

@peterschutt how were you able to verify that things were working with the fix introduced in the linked PR? I tried running the app in this comment after checking out to 680c2df00, but I still was getting this incorrect example. I think I may be doing something wrong.

[tuukkamustonen]

@peterschutt Fixed as suggested in the fixup commit. Great that you spotted that! Take another look.

@guacs I also tried the MVCE there, and it does work for me 🤷🏻‍♂️

[github-actions]

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

[peterschutt]

@peterschutt how were you able to verify that things were working with the fix introduced in the linked PR? I tried running the app in this comment after checking out to 680c2df00, but I still was getting this incorrect example. I think I may be doing something wrong.

My verification was that it was incorrect on main and correct on this branch - given that you get the incorrect behavior on 680c2df00, and I get same on main and 680c2df00 was merged into main, I think we are saying the same thing. Unless I'm misunderstanding (very possible :D)

[peterschutt]

Thanks @tuukkamustonen!