Bug: ResponseHeaders results in invalid OpenAPI schema

[mands]

Description

Use of response_headers on the Litestar object seems to result in invalid OpenAPI 3.1 schema generation.

The Header object on the response is invalid aiui according to the spec (see https://spec.openapis.org/oas/v3.1.0#header-object) and fails validation when using redocly lint, as it includes the name and in fields.

The schema is as follows,

{
    "info": {
        "title": "Litestar API",
        "version": "1.0.0"
    },
    "openapi": "3.1.0",
    "servers": [
        {
            "url": "/"
        }
    ],
    "paths": {
        "/": {
            "get": {
                "summary": "HelloWorld1",
                "operationId": "HelloWorld1",
                "responses": {
                    "200": {
                        "description": "Request fulfilled, document follows",
                        "headers": {
                            "X-Version": {
                                "schema": {
                                    "type": "string"
                                },
                                "name": "X-Version",
                                "in": "header",
                                "description": "Test",
                                "required": false,
                                "deprecated": false,
                                "allowEmptyValue": false,
                                "allowReserved": false
                            }
                        }
                    }
                },
                "deprecated": false
            }
        }
    },
    "components": {
        "schemas": {}
    }
}

URL to code causing the issue

No response

MCVE

from litestar import Litestar, Request, get
from litestar.datastructures import ResponseHeader

@get("/")
async def hello_world1(request: Request) -> None:
    request.logger.info("inside request")
    return None

app1 = Litestar(
    route_handlers=[hello_world1],
    response_headers=[ResponseHeader(name="X-Version", value="ABCD", description="Test")],
)

This endpoint works, but the resulting schema fails validation.

$ litestar schema openapi --output openapi_schema.json
$ npx @redocly/cli lint openapi_schema.json

...
[1] openapi_schema.json:25:33 at #/paths/~1/get/responses/200/headers/X-Version/name

Property `name` is not expected here.

23 |     "type": "string"
24 | },
25 | "name": "X-Version",
26 | "in": "header",
27 | "description": "Test",

Error was generated by the spec rule.


[2] openapi_schema.json:26:33 at #/paths/~1/get/responses/200/headers/X-Version/in

Property `in` is not expected here.

24 | },
25 | "name": "X-Version",
26 | "in": "header",
27 | "description": "Test",
28 | "required": false,
...

Steps to reproduce

No response

Screenshots

No response

Logs

No response

Litestar Version

2.8.2, using Python 3.12.2

Platform

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

---

Note

While we are open for sponsoring on GitHub Sponsors and
OpenCollective, we also utilize Polar.sh to engage in pledge-based sponsorship.

Check out all issues funded or available for funding on our Polar.sh dashboard

• If you would like to see an issue prioritized, make a pledge towards it!
• We receive the pledge once the issue is completed & verified
• This, along with engagement in the community, helps us know which features are a priority to our users.

[peterschutt]

Thanks for reporting!

We go to a lot of effort to document that these shouldn't be included also:

litestar/litestar/openapi/spec/header.py

Lines 18 to 36 in a31d1c6

	class OpenAPIHeader(BaseSchemaObject):
	"""The Header Object follows the structure of the [Parameter
	Object](https://spec.openapis.org/oas/v3.1.0#parameterObject) with the
	following changes:
	1. ``name`` MUST NOT be specified, it is given in the corresponding ``headers`` map.
	2. ``in`` MUST NOT be specified, it is implicitly in ``header``.
	3. All traits that are affected by the location MUST be applicable to a location of ``header``
	(for example, `style <https://spec.openapis.org/oas/v3.1.0#parameterStyle>`__).
	"""
	schema: Schema | Reference | None = None
	"""The schema defining the type used for the parameter."""
	name: Literal[""] = ""
	"""MUST NOT be specified, it is given in the corresponding ``headers`` map."""
	param_in: Literal["header"] = "header"
	"""MUST NOT be specified, it is implicitly in ``header``."""

[github-actions]

This issue has been closed in #3417. The change will be included in the upcoming patch release.

[github-actions]

A fix for this issue has been released in v2.9.0