v3.3: Add a global parameters field - #5446
Conversation
handrews
changed the title
karenetheridge
left a comment
karenetheridge
left a comment
There was a problem hiding this comment.
LGTM. Perhaps add a failing test that shows that query+querystring are prohibited at the global level also (should be able to just copy an existing test)?
This just adds the field without any special handling. It is already possible with the Path Item Object's parameters field to specify parameters that don't make sense for all of the operations, and we don't attempt to compensate for it. The only truly new situation is that there is no one path to which path parameters would correspond. I suspect that global path parameters will be rare, and mostly used in a prefix as more powerful analogues of Server Variables.
|
The rebase was a clean rebase with no changes. |
| | <a name="oas-webhooks"></a>webhooks | Map[`string`, [Path Item Object](#path-item-object)] | The incoming webhooks that MAY be received as part of this API and that the API consumer MAY choose to implement. Closely related to the `callbacks` feature, this section describes requests initiated other than by an API call, for example by an out of band registration. The key name is a unique string to refer to each webhook, while the (optionally referenced) Path Item Object describes a request that may be initiated by the API provider and the expected responses. An [example](https://learn.openapis.org/examples/v3.1/webhook-example.html) is available. | | ||
| | <a name="oas-components"></a>components | [Components Object](#components-object) | An element to hold various Objects for the OpenAPI Description. | | ||
| | <a name="oas-security"></a>security | [[Security Requirement Object](#security-requirement-object)] | A declaration of which security mechanisms can be used across the API. The list of values includes alternative Security Requirement Objects that can be used. Only one of the Security Requirement Objects need to be satisfied to authorize a request. Individual operations can override this definition. The list can be incomplete, up to being empty or absent. To make security explicitly optional, an empty security requirement (`{}`) can be included in the array. | | ||
| | <a name="path-item-parameters"></a>parameters | [[Parameter Object](#parameter-object) \| [Reference Object](#reference-object)] | A list of parameters that are applicable for all operations in this API. These parameters can be overridden at the path item or operation levels, but cannot be removed there. The list MUST NOT include duplicated parameters. A unique parameter is defined by a combination of a [name](#parameter-name) and [location](#parameter-in). The list can use the [Reference Object](#reference-object) to link to parameters that are defined in the [OpenAPI Object's `components.parameters`](#components-parameters). | |
There was a problem hiding this comment.
How does this interact with definitions split across multiple files? The restriction
cannot be removed there
Makes me worried that this will not be useful outside of very narrow use cases, though if it is scoped to the file it is defined in then it might be fine (though bring it's own complexities).
Eg: I could imagine using this for authentication related headers, but often you might have a handful of authentication related routes (for login, token refresh, password reset) that don't want those headers.
The other main use case I picture is flow control/rate limit related headers which might be ok without any scoping.
By multiple files, I mean I normally structure things like
openapi.yaml <- all routes exposed by the service using $ref to the other files
docs/auth.yaml <- auth related routes
docs/foo.yaml <- routes/schemas for the foo domain
...
docs/common.yaml <- cross cutting schemas like error responses
I'd wonder if being able to specify (name, in, schema: null) or similar on a route/operation level to remove the parameter would be worthwhile.
There was a problem hiding this comment.
Good point. Can we consider the overriding mechanism as a way to "remove" by nulling it out down stream?
There was a problem hiding this comment.
I shudder at the idea of schema: null. But I think schema: false should probably do just what you want.
There was a problem hiding this comment.
@mikekistler is correct. null is not a valid schema but false is.
@mnahkies We expect this to have a fairly narrow use case, and probably more for request headers or cookies than query params (or certainly path params).
Document vs API scope is a mess, currently, and there's really no way to fix it until 4.0. Things at the root level (except the Info Object) are all scoped at API level (security and servers), so parameters should probably follow that rather than create yet another usage pattern (as @baywet has noted, we have too many already).
There was a problem hiding this comment.
How does this interact with definitions split across multiple files?
I'm hoping to clarify some of this a bit in 3.3. But currently I would say that global parameters applies in exactly the same way as global servers, securitySchemes and tags do. I have my own personal interpretation of how this works today, but this may differ from others' interpretations, which is why I hope to clarify the current state and then use that to move forward with more features to allow more flexibility in how APIs are defined with multiple documents.
There was a problem hiding this comment.
That all makes sense.
To be clear my concern on the narrow use case is that even for headers and cookies, it may often not be useable if there is no way to remove it from a few specific operations.
schema: false would work for me.
(I can think of ways to hack around being unable to remove parameters from operations but I don't particularly like them and think it would muddy the conversation)
There was a problem hiding this comment.
@mnahkies While technically the spec does say that you can't remove a parameter at the Operation Object level (and therefore with this new addition, also at the Path Item Object level), setting schema: false effectively does this. The UX isn't great because documentation tools will still show it, but a false schema forbids all values so even if it is there it is not usable.
5 participants
Fixes #5320 : Add global
parametersfield without changing any of the ways in which parameters behave at different levels.This is the simplest expansion, and should support known use cases like universal request headers or cookies.
This feature does not interact productively with
in: querystring, and that should be fine for now. We can add complexity there if and when clear use cases emerge. It is not even entirely clear how common a globalin: queryparameter (which would prevent use ofin: querystringeverywhere) would be.Global path parameters would also be odd, but could be used somewhat like Server Variables. The oddness of them does not seem sufficient reason to forbid them, although I could be persuaded given that they would not be clearly associated with any one path template.