Add support for Path Item and Operation servers (v3)

[krokettenkoal]

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 using https://maps.googleapis.com as an endpoint, while the Roads API is using https://roads.googleapis.com, and the Geolocation API is using https://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 the Service and Operation 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, the ApiRequestOptions type now includes an optional server property as well, which is set to the according Service's or Operation's server URL (preferring operation-level servers to path-level servers) when making a request. The provided server is then considered in the client's getUrl() 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.