Bug: OpenAPI schema generation for `msgspec.Struct`s is woefully lacking

[umarbutler]

Description

Currently, despite Litestar being meant to have first-class support for msgspec:

1. Litestar's documentation does not document any way of customizing the titles, descriptions, examples, and other metadata of msgspec structs.
2. msgspec.Meta annotations applied to msgspec structs are largely ignored by Litestar.
3. msgspec.Meta annotations applied to ClassVar fields such as tag fields are ignored when generated OpenAPI specs.
4. Litestar does not emit the required discriminator annotation for custom msgspec tag fields annotated with ClassVars.

It is proving very difficult to build a production API with litestar and msgspec given the above issues.

URL to code causing the issue

No response

MCVE

Steps to reproduce

1. Go to '...'
2. Click on '....'
3. Scroll down to '....'
4. See error

Screenshots

No response

Logs

Litestar Version

2.19.0

Platform

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

[euri10]

The best way to move this forward is probably to tackle the individual issues you’ve already opened.
OpenAPI support is an area where contributions are very welcome, and folks more familiar with that part of the codebase can help review or guide changes.
I personally don’t use it at all, and don’t have much familiarity with that portion of the code, so I’m unlikely to be the one driving fixes there, but I'm sure others will.

[winstxnhdw]

Is there even a way to map tag fields to an OpenAPI spec?

[umarbutler]

@winstxnhdw Yes, it's called a 'discriminator field': https://bump.sh/blog/the-discriminator-in-openapi-is-generally-redundant-and-confusing/

[winstxnhdw]

Seems like Pydantic has this since 2021. This might be worth looking into. pydantic/pydantic#2336

[provinzkraut]

Litestar's documentation does not document any way of customizing the titles, descriptions, examples, and other metadata of msgspec structs.

That's because there's nothing specific to msgspec.Struct. Litestar's modelling support is not built around specific libraries, but generic functionality that can be made to work via plugins with 3rd party libraries. The way you customise the examples for a Struct is no different than you would for a dataclass or a Pydantic model.

msgspec.Meta annotations applied to msgspec structs are largely ignored by Litestar

It would be helpful if you submit a issue with a concrete example of what's going wrong there.