Add support for Path Item and Operation servers (v3) #1669
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
Currently, servers defined inside Path Items and Operations in OpenAPI3 specifications are ignored, and the (first) server specified in the OpenAPI Object is used for every request. This may break clients for APIs using different service endpoints on path-level or operation-level.
Example
The Google Maps Platform OpenAPI3 Specification defines different service endpoints (servers) for some APIs (paths), with the base server being
https://www.googleapis.com
. For example, the Places API is usinghttps://maps.googleapis.com
as an endpoint, while the Roads API is usinghttps://roads.googleapis.com
, and the Geolocation API is usinghttps://www.googleapis.com
.When generating a client from the provided OpenAPI3 specification (YAML or JSON), the resulting services and their operations always send their requests to the base server URL
https://www.googleapis.com
, breaking all APIs that use servers other than the base server (in this case: most of them).Solution
Path-level and operation-level servers are already being parsed from v3 specifications. However, their values are not used when exporting (generating) services and operations. This PR addresses this issue by including an optional
server
property in theService
andOperation
interfaces, which is set by the parser to the first server's URL in the corresponding Path Item Object or Operation Object (if available). Additionally, theApiRequestOptions
type now includes an optionalserver
property as well, which is set to the accordingService
's orOperation
's server URL (preferring operation-level servers to path-level servers) when making a request. The provided server is then considered in the client'sgetUrl()
function, falling back to the base server if the request options do not contain a server URL (or the URL is empty).Remarks
I have originally seen this functionality as a new feature. The more I think about it, however, the more it seems like a bugfix to me, as it is described in the OpenAPI3 specs and may cause broken services and/or operations when missing. It does not appear to be too critical, though.