microsoft
Extend OpenAPISpecGeneratorPlugin to include default values for parameters
Azure API endpoints use the api-version query string parameter to version endpoints.
When using Dev Proxy to generate an OpenAPI spec the api-version parameter in not included in the generated document. This leads to an error when issuing a request as the api-version parameter is not sent.
We should look to include this as a parameter in generated documents with a default value.
parameters:
- name: api-version
in: query
required: true
schema:
type: string
default: "2024-11-01-preview"
OK, so I can see the param included in the generated spec but it's missing the default value:
We can definitely include the specified value as default. What do you think: should we do it by default, or should it be an option, like currentValueAsDefault, which is set to false by default but when set to true copies the values from the intercepted requests as defaults?
I see also that in the generated spec, the param is not marked as required. Do you know if that's necessary for agents to always include the param in the API request?
should we do it by default, or should it be an option, like currentValueAsDefault, which is set to false by default but when set to true copies the values from the intercepted requests as defaults?
I think for ease it would be easier to use the value from the request as the default value.
Thinking about it some more, should we have an array of known parameters like api-version in the configuration, but which developers can override with their own param names?
I see also that in the generated spec, the param is not marked as required. Do you know if that's necessary for agents to always include the param in the API request?
In this case yes, not sending the param results in an error from the API.
I think for ease it would be easier to use the value from the request as the default value.
The reason I'd prefer to expose it via an option and an explicit opt-in is because of potential PII that could end up in the spec.
Thinking about it some more, should we have an array of known parameters like api-version in the configuration, but which developers can override with their own param names?
We already have a list of standard headers. We could go about it in two ways:
- Allow customers to specify parameters to exclude and we include everything else
- Allow customers to specify parameters to include and we exclude everything else
We could offer both options and customers can decide which way they want to go about it.
Good shout on PII, then an option makes sense.
I'd say go with an include list, option 2.
working on it.
Summarizing, We need the following:
- add a config property of the plugin named like ParametersWithDefaults or DefaultedParameters with an array of strings;
- capture parameters from query string applying the case-sensitive comparison;
- render the spec as described in the issue. The included parameter must also have two attributes required=true and default=
.
@waldekmastykarz How does that sound?
Noticed that the plugin does not handle query string arrays (multiple the same parameter), in the case, the value is a string and rendered as "val1,val2,val3".
How about we named the configuration value IncludeParameters? Other than that, agree with what you proposed. We appreciate your help!