Group multiple parameter definitions for better maintainability #34
Comments
|
Thanks for opening the issue, there's just one thing that's not clear. On one hand, you're saying that you want to provide them for 'every path' which implies a global definition that won't require you to reference it, and on other hand, you go ahead and reference from a specific method to the group of parameters. So which of the two are you looking for? or is it both? |
|
Ok the formulation every path is maybe wrong (too open). We still have paths which do not need this parameter. We would like to use it as described in the example to reference a group of parameter with one reference. Otherwise it would look like this: /test/:
get:
tags:
- TEST
operationId: routes.test
parameters:
# In path parameter
- $ref: "#/parameters/event_type"
- $ref: "#/parameters/appearance_date"
# Meta Data Properties
- $ref: "#/parameters/param1"
- $ref: "#/parameters/param2"
- $ref: "#/parameters/param3"
- $ref: "#/parameters/param4"
- $ref: "#/parameters/param5"
- $ref: "#/parameters/param6"
# Data Properties
- $ref: "#/parameters/param7"
- $ref: "#/parameters/param8"
- $ref: "#/parameters/param9"
- $ref: "#/parameters/param10"
# Specific Properties
- $ref: "#/parameters/param11"
- $ref: "#/parameters/param12"
- $ref: "#/parameters/param13"
- $ref: "#/parameters/param14"
- $ref: "#/parameters/param15"
- $ref: "#/parameters/param16"
- $ref: "#/parameters/param17"
responses:
200:
description: OKWith the enhancement we could write it like this and manage the items of each group in one place: /test/:
get:
tags:
- TEST
operationId: routes.test
parameters:
# In path parameter
- $ref: "#/parameters/event_type"
- $ref: "#/parameters/appearance_date"
# Meta Data Properties
- $ref: "#/parameters/MetaDataParamGroup"
# Data Properties
- $ref: "#/parameters/DataParamGroup"
# Specific Properties
- $ref: "#/parameters/SpecificParamGroup"
responses:
200:
description: OK |
|
Okay, thank you for the clarification. The reason I asked is because we have a feature request for global parameters already. People have asked for parameter groups in various places, but nobody opened a feature request, so thank you for taking the time to do so. The value of it is understandable. I'm not sure the syntax you shared works, but we can evaluate it further over time. |
|
If |
|
@mohsen1 Ok and what is the problem with hashes for parameters? Is there a discussion in another issue about this? |
|
|
|
@cansik For your request, I suggest that you define your own vendor extension for parameter groups, and write a processing tool that would inline your group references into a pure Swagger 2.0 spec for external consumption. I already find that many tools do not fully support the current spec (for example I found issues with |
|
+1 |
|
+1 |
|
+1 this would save me a lot of time and lines in my doc spec |
|
+1 this too, everything that gets me to reuse code is a huge +1. |
|
+1 |
|
+1 |
|
It's worth noting that RAML take on this, 'traits' (really not much different from the proposed structure). |
|
+1 |
|
Reference OAI/OpenAPI-Specification#560 |
|
+1 |
1 similar comment
|
+1 |
|
Just as a note for everyone wanting to vote this up: Github recently added a feature allowing a "reaction" to each post, using the button in the top left corner of each post. This will not clutter the thread with contentless comments. |
|
How about allowing us to organize parameters into sets? This is analogous to (I don't think there is a UI aspect to these sets, so no set descriptions are needed. Syntax for describing parameter sets would be added for documentation purposes, though.) |
|
+1 |
|
@OAI/tdc propose closing this with no action. The fix in OAI/OpenAPI-Specification#633 will help with this |
|
I think we still need to support this, and should be fairly easy. OAI/OpenAPI-Specification#633 doesn't really help with this. This is not about global parameters, and reusable parameters existed in 2.0 already. |
|
FWIW, I would like OAS to use structural abstractions (such as the tags I suggest above) over |
|
I agree with @webron that sets deserve consideration on their own. |
|
Hello from 2022, +1 |
|
This is one of the items we consider and hope to solve using Overlays. You can follow this discussion to get more information. The README in the repo is very empty right now, but we'll add more information there. We also have regular meetings for Overlays which everyone is welcome to join (info will be added to the readme). |
|
Still hoping for the best 🥲 |
|
When does this feature be implemented? |
|
Love to have this feature soon. |
|
I will take a look at if/how overlays can solve this problem. This is part of determining whether overlay spec is sufficient, so I won't comment on other solutions now. I'm not a member of the steering committee, just a developer who would like to see overlays become reality. I did not read every comment on this issue. For @cansik's original request, an overlay solution might look like {
"overlay": "1.0.0",
"info": {
"title": "Default Parameters Overlay",
"version": "1.0.0"
},
"actions": [
{
"target": "info",
"update": {
"x-overlay-applied": "default-parameters"
}
},
{
"description": "Add default perameters to all operations",
"target": "paths.*.*",
"update": {
"parameters": [
{
"name": "id",
"in": "query",
"description": "Entry identification number",
"required": false,
"schema": {
"type": "integer"
}
},
{
"name": "time_start",
"in": "query",
"description": "Start time of flare",
"required": false,
"schema": {
"type": "string"
}
},
{
"name": "nar",
"in": "query",
"description": "Active region number",
"required": false,
"schema": {
"type": "string"
}
}
]
}
}
]
}Or applying parameters only to operations with a particular tag (traits could be used instead) {
"overlay": "1.0.0",
"info": {
"title": "Default Parameters Overlay",
"version": "1.0.0"
},
"actions": [
{
"target": "info",
"update": {
"x-overlay-applied": "default-parameters"
}
},
{
"description": "Add default perameters to all operations",
"target": "paths[*][?(@.tags == 'pets')]",
"update": {
"parameters": [
{
"name": "id",
"in": "query",
"description": "Entry identification number",
"required": false,
"schema": {
"type": "integer"
}
},
{
"name": "time_start",
"in": "query",
"description": "Start time of flare",
"required": false,
"schema": {
"type": "string"
}
},
{
"name": "nar",
"in": "query",
"description": "Active region number",
"required": false,
"schema": {
"type": "string"
}
}
]
}
}
]
} |
|
I love this feature soon |
|
the demand persists even in 2023 :) |
|
My recomendation is to do something about it instead of wondering why its not been done.
Can somebody take a swing at a proposal PR instead of just hoping somebody else does it? |
|
We already use json schema everywhere, parameters could be broken down, query, path. headers, and we could just use json schema paths:
/things:
query:
oneOf:
- type: object
properties:
startDate: ...
endDate: ...
- type: object
properties:
startIndex: ...
endIndex: ... |
|
Almost 2024 and we're still waiting for this? |
|
+1 how many more comments are needed till we have this feature done? |
|
+1 - This is all I want for christmas |
|
+1 - I want to start my 2024 with a smile please :') |
|
+1 Santa this is my wish |
I think more correct question would be: Where can we donate to have all these features done? =) |
|
I'm going to move this to the Overlays repository as suggested by a previous comment, but note also that this sort of thing is being discussed for v4 of OpenAPI over in the sig-moonwalk repository. |
|
There's a valid example further up the thread, and here's my working example in YAML that adds the parameters to all get requests: overlay: 1.0.0
info:
title: Add parameters to every endpoint
version: 0.1.0
extends: file:///home/lorna/demo/overlays-traits-example/museum.yaml
actions:
- target: $.paths.*.get
update:
parameters:
- name: id
in: query
description: Entry identification number
required: false
type: integer
- name: time_start
in: query
description: Start time of flare
required: false
type: string
- name: nar
in: query
description: Active region number
required: false
type: string
You can do this today using any of the published overlay tools such as the CLIs from Speakeasy and Bump.sh. I'm going to close this issue since I do feel that the question is answered, but do follow up with new issues or discussions around this feature or similar use cases - we're happy to hear feedback at this early stage. |
|
But this is not the specific function that is asked for in the OP, or by many of us. This is only a solution if you want to put this combination of parameters on ALL endpoints of a certain type. The option to bundle parameters and reference them on most, but not all of my endpoints, or have somewhat different bundles of parameters I can reference is not fixed with this solution. It's been open for close to 10 years and now we're closing the issue because there's a somewhat related option to do something similar but not actually adress this specific problem? If we just decide that this will never be relevant or useful that's one thing, but the solution of just defining things on ALL gets or endpoints is not even what the very first example by OP showcases. It's about referencing a bundle of parameters that makes it easy to maintain several re-useable bundles of parameters and a function like that would still be of great use to us. The best example we are currently encountering is a set of standard parameters we have for 70% of our endpoints, but not all of them, and the logic on which do or don't is not as simple as "all gets". Currently this means referencing 5 different parameters on those endpoints, as we want to still maintain them somewhere else, instead of doing it like in the OP and there's still no fix for it afaik. |
|
@antonMetodika Probably, we need to open a new issue on OpenAPI specs. BTW, when this issue was created, there was no overlay specs. |
|
@antonMetodika @sharmasourabh this got moved to Overlays because the discussions became mostly about "traits". For OAS 3.x, there are several issues already tracking grouping and re-use:
These sorts of topics are also being discussed for the next major version at OAI/sig-moonwalk. |
|
@antonMetodika I think Overlays can still help in the use case that you mention, but the mechanics are a bit different. For example, you could use a particular tag or even an extension on the endpoints in OpenAPI that should get the group of parameters applied (or tag the ones that should not, if that's easier!) - and then Overlays can add the group of parameters to those endpoints. I did post a simplified example, but we can expand it for something more specific to your use case if that would make it clearer how it can meet your needs? |
|
@lornajane Thank you for clarifying, for some reason I did not make the connection that I can use that with custom tags rather than just on all get/post etc. endpoints. I think the example in the closing comment could benefit from that clarification so slow people like me can make sense of it faster! :D If it works as described I think this covers the use cases I can think of pretty well, thanks again! |
and others
Idea
Sometimes you have some parameters you want to provide on every path. At the moment it is possible to reference them with the
$reftag. This works great if you have a lot of different parameter combination for each route.But we now have a complex api with a lot of optional get parameters for every path. Now the problem we encounter is, that if we have to add new parameters to this get parameters, it is very cumbersome and inconvenient to set the reference to them on each path. Often it happens that you forget one.
It would be great if we could group parameter definitions for a better maintainability and usability.
Example
As already presented on stackoverflow here an example of the definition (how it could look like):
And here is how I would like to reference it:
To get more on the user experience, this definition is much more readable than 20 parameters for each route.
Other Ideas?
Have you already thought about something like this or do you want us swagger users to go another way to deal with this problem?
Regards
Florian
The text was updated successfully, but these errors were encountered: