Extend OpenAPISpecGeneratorPlugin to include default values for parameters

[garrytrinder]

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"

[waldekmastykarz]

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?

[garrytrinder]

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.

[waldekmastykarz]

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:

1. Allow customers to specify parameters to exclude and we include everything else
2. 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.

[garrytrinder]

Good shout on PII, then an option makes sense.

I'd say go with an include list, option 2.