Global, implicit parameters in client

[atombender]

Is there a way to recognize that certain parameters are present on all endpoints and should be set out-of-band?

For example:

• An API version parameter /v{version}
• A request tag parameter: tag=foo

At the moment, these must defined something like:

paths:
  /{version}/projects:
    get:
      summary: Lists projects
      operationId: listProjects
      parameters:
      - $ref: '#/components/parameters/versionParam'
      - $ref: '#/components/parameters/tagParam'

# ...

components:
  parameters:
    tagParam:
      name: tag
      description: Request tag
      required: false
      in: query
      schema:
        type: string

    versionParam:
      name: version
      in: path
      description: API version
      required: true
      schema:
        type: string

Which generates a signature like this:

ListProjects(ctx context.Context, params ListProjectsParams) ([]Project, error)

with a type:

type ListProjectsParams struct {
	Version string
	Tag     string
}

This is tedious to fill in at every client call site. In particular:

• The API version is tied to the API as a whole, so every single API call will use the same API version, but it has to be filled in at every call site.
• A request tag might be derived from something, e.g. an automated test name, so would benefit from being set through a context.

Instead, it would be nice to be able to mark these parameters as either "client-level" or "contextual", so you could have client code like this:

client := someapi.NewClient(url, someapi.WithVersion("2024-06-29"))

// Example call:
ctx := someapi.CtxWithTag(t.Name)
resp, err := client.ListProjects(ctx) // ← Note, no ListProjectsParams needed

The only way to work around this at the moment, as far as I know, is to pass in empty strings here, and then wrap the client in something that injects the data into every call, which is not very convenient. (The tag could be injected as an http.Client wrapper which looks at whether the URL contains a tag and otherwise adds it. But the version is a path parameter, so this wouldn't work there.)

Are there other workarounds?

[atombender]

Ah, looks like an out-of-band API version can be injected via a servers list and a base URL.