Problem description
I noticed that we are misusing variables in servers.url properties in most API definitions.
Commonly we define servers as, e.g.:
servers:
- url: "{apiRoot}/{basePath}"
variables:
apiRoot:
default: http://localhost:9091
description: API root
basePath:
default: qod/v0
description: Base path for the QoD API
But basePath which is the api-name and major version is not something that may be changed by the client. default is defined in OAS as:
| Field Name |
Type |
Description |
| default |
string |
REQUIRED. The default value to use for substitution, and to send, if an alternate value is not supplied. Unlike the Schema Object's default, this value MUST be provided by the consumer. |
We are not allowing an alternate value to be supplied by the API client, so this part of the servers.url must be fixed.
Possible evolution
Proposal is to redefine servers as, e.g.:
servers:
- url: "{apiRoot}/qod/v0"
variables:
apiRoot:
default: http://localhost:9091
description: API root
Problem description
I noticed that we are misusing variables in servers.url properties in most API definitions.
Commonly we define
serversas, e.g.:But
basePathwhich is the api-name and major version is not something that may be changed by the client.defaultis defined in OAS as:default, this value MUST be provided by the consumer.We are not allowing an alternate value to be supplied by the API client, so this part of the
servers.urlmust be fixed.Possible evolution
Proposal is to redefine
serversas, e.g.: