OpenAPI operations include parameters disallowed by OpenAPI 3.0 specification

[martincostello]

Is there an existing issue for this?

• I have searched the existing issues

Describe the bug

According to OpenAPI Guide: Describing Parameters, certain HTTP headers are disallowed from being documented as parameters of operations:

Note: Header parameters named Accept, Content-Type and Authorization are not allowed.

Instead, they should be documented elsewhere (responses.<code>.content.<media-type>, requestBody.content.<media-type>/responses.<code>.content.<media-type> and securitySchemes/ security respectively).

Endpoints using [FromHeader(Name = "{name}")] to bind any parameters have these parameters included in the endpoint documentation, violating this requirement.

Expected Behavior

Header parameters for Accept, Content-Type and Authorization are not included in operations' parameters.

Steps To Reproduce

Define an HTTP endpoint similar to the following:

app.MapGet((
    [FromHeader(Name = "Accept")] string accept,
    [FromHeader(Name = "Authorization")] string authorization,
    [FromHeader(Name = "Content-Type")] string contentType) =>
{
    // ...
});

Exceptions (if any)

No response

.NET Version

9.0.100-rc.1.24413.1

Anything else?

Spotted after looking into domaindrivendev/Swashbuckle.AspNetCore#3024 (comment), which then reminded me that in an application of my own the Authorization parameter had re-appeared after migrating to OpenAPI from Swashbuckle.AspNetCore (OpenAPI document diff Swashbuckle.AspNetCore 6.7.0 to M.A.OpenApi 9.0-preview.7).

[captainsafia]

I'm observing some ambiguity in the docs around this. The Swagger documentation page linked above does indeed say:

Note: Header parameters named Accept, Content-Type and Authorization are not allowed. To describe these headers, use the corresponding OpenAPI keywords:

And instruct users to instead set other fields in the property per the following rules:

However, the OpenAPI spec itself seems to take a much less perspective stance as documented here.

If in is "header" and the name field is "Accept", "Content-Type" or "Authorization", the parameter definition SHALL be ignored.

This may very well be something that changed in a patch version of the spec.

My two cents on this based on the frameworks behavior: I think it's totally reasonable to document parameters that are sourced from the header, even if they are special headers like Authorization or Accepts. Just because you try to bind from the Accepts header in your route handler, doesn't mean you've actually configured accept content types for your request body, that's managed by other APIs. Similarly, just because you're trying to bind to the Authorization header, doesn't mean you've actually configured security requirements on your endpoints.

I'd like to hear @mikekistler's thoughts on this from the spec side of things. It seems like what we are doing is compliant with v3.0.3 of the spec.

[mikekistler]

I agree that it should be possible for a route handler to access the values of these headers by declaring them as FromHeader parameters, so the question is whether these should make their way into the OpenAPI doc.

The quote @captainsafia references above was in the spec since OpenAPI 3.0.0. And while the language stops short of saying that an OpenAPI definition is invalid if any of these headers are present, it does make it pretty clear that they should be ignored by any tooling reading that definition, making them not particularly useful.

I would lean towards filtering these out when generating the OpenAPI doc. Leaving them in may be compliant, but I don't believe it adds value.

[captainsafia]

Thanks for chiming in, @mikekistler!

I'm gonna go ahead and stick this in .NET 10 Planning for now as I don't think we'll be able to get this in before RC1 snap and I don't think this meets the RC2 bar.

[martincostello]

I'll try and pick this up today - feels like it would be simple enough.

[captainsafia]

I'll try and pick this up today - feels like it would be simple enough.

Thank you! My day today was a little booked and I didn't want to make any promises about things we could squeeze in before code complete. 😅 I'll take a look at your PR.

[martincostello]

✨ Be the change change the code you want to see in the world repo ✨