Summary

The current OpenAPI example generation is a bit of a mixed bag, and this issue collects the various separate issues and documents some extra needs.

1. Support ResponseSpec(examples=...) for custom response examples

   This is #3068 (merged)

The example generation is turned off by default, but can be enabled by Litestar(openapi_config=OpenAPIConfig(create_examples=...)).

Yet, with example generation off:

2. Examples are generated for error responses:

                     "examples": {
                       "NotAuthorized": {
                         "value": {
                           "status_code": 401,
                           "detail": "Missing or invalid credentials",
                           "extra": {}
                         }
                       }
                     }
                   }

   This is not tunable, they are always there. Would expect these to not exist by default (with example generation turned off).

3. Examples are generated for response models:

   Even with Litestar(openapi_config=OpenAPIConfig(create_examples=False)) (default), OpenAPI $.components.schemas models get examples.

   Turning ResponseSpec(..., generate_examples=False) disables this, but you'd expect the global flag to do the same first.

   This one was invalid report, it actually worked just fine. Ignore this bullet.

Once you actually set Litestar(openapi_config=OpenAPIConfig(create_examples=True)), you will get examples for:

• Query, Path, Header, Cookie parameters
• Request bodies
• Response bodies

3. It's possible to locally turn example generation off per ResponseSpec but not per Parameter

   Allow Paremeter(generate_examples=False) to sync with ResponseSpec support.

4. The generated examples are inserted as both OpenAPI and JSON schema examples, ie:

                       {
                           "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"
                               }
                           }
                       }
   

   It maybe feels a bit unnecessary to do both, when OpenAPI ones should suffice.

   Example generation could be a toggle instead of a flag. It could support 4 modes:

   1. OpenAPI schema only
   2. JSON schema only
   3. Both JSON + OpenAPI
   4. None

   Litestar uses (3), generating examples in both. Even if this toggle doesn't get implemented, I believe it's good to identify the case here.

   This is #3057.

5. The order of OpenAPI schema changes between executions

   This is #3059 (merged).

6. Define examples in Pydantic (and Msgspec, dataclass, TypedDict) models

   This already works for Pydantic's Field(examples=[...]), but not for ConfigDict(json_schema_extra=...). There should also be a mechanism to define the examples for the model, within the model (not only per field). (It was deemed somewhere that Pydantic's json_schema_extra wouldn't be supported, but there needs to be some mechanism for this, like for Msgspec, dataclass, et al).

   Support for declaring query/path/header/cookie arguments as models is tracked in #2015. This is probably related, once there's full support for those, also defining examples in the models probably gets supported?

7. dict[str, Any] and None trigger example generation always

   This is #3069 (merged)

Basic Example

No response

Drawbacks and Impact

No response

Unresolved questions

No response