Enhancement: Only generate example once when `Parameter(examples=[...])` is specified for path arg and its schema about litestar

[provinzkraut]

Not really a bug I think but rather an enhancement. We have a few instances where this kind of duplication occurs and it's reasonable to optimise some of these away. Iirc @peterschutt you were discussing a similar case recently regarding DTOs?

[tuukkamustonen]

This perhaps-too-eager-example-generation also applies to the response examples created via OpenAPIConfig(..., create_examples=True) as well, e.g.:

  "components": {
    "schemas": {
      "Response": {
        "properties": {
          "text": {
            "type": "string",
            "examples": {
              "text-example-1": {  <---- example per field, unnecessary?
                "description": "Example text value",
                "value": "DwEkQQHiBrmXZcSFtoJx"
              }
            }
          },
          "num": {
            "type": "integer",
            "examples": {
              "num-example-1": {  <---- example per field, unnecessary?
                "description": "Example num value",
                "value": 4966
              }
            }
          }
        },
        "type": "object",
        "required": [
          "num",
          "text"
        ],
        "title": "Response",
        "examples": {
          "response-example-1": {  <---- example per model, this is ok
            "description": "Example  value",
            "value": {
              "text": "IgNZYFcagWptUqCwdERi",
              "num": 3674
            }
          }
        }
      }
    }
  }

I don't know if the GUIs actually need or benefit from field-specific examples, but perhaps the model level one would suffice.

[provinzkraut]

I don't know if the GUIs actually need or benefit from field-specific examples, but perhaps the model level one would suffice.

IMO as long as we don't have more granular settings for turning example generation on/off, generating them everywhere it's supported is the more reasonable approach since it covers more use cases. Say we don't generate examples for the fields but a user wanted examples generated for that, they would have no way of turning this on. This way, we might make the schema a bit more verbose, but it actually doesn't do any harm to have these examples in there.

[tuukkamustonen]

That's a fair statement. All off by default, all enabled with create_examples=True.

However, currently errors do get examples by default, e.g.:

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

That's an exception to the rule.

And then you allow disabling example generation with ResponseSpec. Another exception, perhaps (but no harm in that).

---

I guess there are roughly 4 modes here:

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

There could be a toggle, but I agree that global on/off should be sufficient, as the OpenAPI schema is really intended as machine-readable and not really for humans.

(The other issue #3058 confused me a bit here.)