Is it possible to document headers for multiple responses in OpenAPI?

[sayandipdutta]

I am writing a put endpoint, where if the resource does not exist, a resource will be created with 201, otherwise it will be updated with 200. I also want to add etag and Location headers:

I tried the following:

    @put(
        path="/config/{project_name:str}",
        etag=ETag(documentation_only=True),
        response_headers={
            "Location": ResponseHeader(
                name="Location",
                documentation_only=True,
                description="Relative URI of the created/updated resource",
            )
        },
        responses={
            201: ResponseSpec(
                UUID,
                description="Configuration created",
            ),
            200: ResponseSpec(
                UUID,
                description="Configuration updated",
            ),
        }
    )
    async def update_configuration(
        self, project_name: str, data: Annotated[ProjectConfig, Body(title="Project Config")],
    ) -> Response[UUID]:
        ...

This does not work, the generated documentation for responses does not contain headers section. Even if it had worked, I would have preferred something like this:

    @put(
        path="/config/{project_name:str}",
        responses={
            201: ResponseSpec(
                UUID,
                description="Configuration created",
                headers={
                    "ETag": ETag(documentation_only=True),
                    "Location": ResponseHeader(
                        name="Location",
                        documentation_only=True,
                        description="Relative URI of the created resource",
                    )
                },
            ),
            200: ResponseSpec(
                UUID,
                description="Configuration updated",
                headers={
                    "ETag": ETag(documentation_only=True),
                    # Let's say response with 200 will not have a `location` header
                }
            ),
        }
    )
    async def update_configuration(
        self, project_name: str, data: Annotated[ProjectConfig, Body(title="Project Config")],
    ) -> Response[UUID]:
        ...

which is currently an error, as ResponseSpec does not take a headers argument.

Am I doing something wrong? Or is it not possible?

[vinicq]

You're not doing anything wrong. ResponseSpec doesn't expose a headers argument right now, so the per-status-code shape in your second snippet isn't expressible.

What I've fallen back to. response_headers on the handler applies uniformly to every response, so if a header only makes sense for one status I keep response_headers for the always-present ones (ETag in your case) and document the conditional one (Location, 201 only) in the description text of the matching ResponseSpec. Reads fine in the generated docs even if it's a little ugly.

For tighter control of per-status headers in the generated OpenAPI spec, you can post-process the schema with an on_app_init hook that patches the components after the schema is built. Heavier hammer.

Worth filing as a feature request if there isn't one already. OpenAPI 3.x supports headers per response object natively, and the shape you sketched (ResponseSpec(..., headers={...})) maps onto it cleanly. The surface change is small: a headers field on ResponseSpec and a couple of lines in the schema generator to feed it in.