Accept/Content-Type/Authorization Ignored

[jaydreyer]

Hi all,

I work at a company that requires Swagger/OpenAPI specs for every API, so we have about 1500+ specs right now; probably 85% are using Swagger 2. I'm going to start requiring everyone to use OpenAPI 3.x going forward, primarily because it's waaay past time we did this. I'm also trying to make it easier for specs to be downloaded and imported into Insomnia or Postman and not have duplicate params that will cause confusion.

I've got a couple of issues, however, that are holding me up.

1. We have more than a couple APIs that, for whatever reason, have required Accept or Content-Type header params. Is there a way to still have these using the OpenAPI 3.x rules/structure? Do we just flat-out tell teams not to add these header params?
2. For years we have told teams that key is a required query param (or x-api-key header), and Authorization is a required header param if auth is being used. I understand these move into the security/securityScheme sections. Has anyone run into issues with people being confused about the new location of these values? Like I said, previously these were easy to see in the param list in Swagger-UI, but going forward, they are behind the padlock icon, which is a bit different.

Sorry for the long note. I'm just hung up on #1, and worried about #2 (especially since we've made a big deal about "keys are for tracking, not security" and now they are in the security section). I'm curious if others have had to deal with this and what has worked for them.

Thanks!

[webron]

1. That was indeed one of the stricter changes from 2.0 to 3.0. You simply cannot have those as defined headers anymore as those are exclusively defined under content now. If you're using any conversion tools, they may be able to support it (or extended to support it). Adding those headers in 3+ is a no-go and should fail validation.

2. key or x-api-key could have been defined in 2.0 as well under the security sections. I don't believe there's any requirement for you to move them to become security definitions rather than parameters in 3.0. The benefit of moving them to the security section is that that you're not going to have to add them to each and every operation. authorization is strictly prohibited as a header parameter name and that has to move to the security section.

[jaydreyer]

Thanks, @webron. So, if an older spec has content-type/accept as a required header param, other than changing their code is there anything we can do in the spec to indicate it is required?

[webron]

There isn't, as far as I can tell. While technically they shouldn't be required, I can understand limitations in existing applications. There are implementation workarounds if you want to proceed with the migration but not change the code.

[jaydreyer]

Hi @webron. Circling back on this after a few months...is there a good explanation for why authorization is strictly prohibited as a header param? I'm re-writing docs and I know I'll end up getting this question.

[webron]

Because it can/should be specified using the security schemes in the spec.

[handrews]

Looks like this discussion resolved back in 2022, closing.