Add support for Path Item and Operation servers (v3) #1669
Conversation
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
OS-agnostic unit tests
Services and operations generated from OpenAPI v3 specifications now respect servers defined in Path Items (see https://spec.openapis.org/oas/v3.1.0#path-item-object) and Operations (see https://spec.openapis.org/oas/v3.1.0#operation-object). This implies the following changes: * Service.d.ts and Operation.d.ts now include an optional `server` property, being set to the first server's url of the `servers` property in their corresponding Path Item Object or Operation Object in the spec. The behavior is the same as with the `OpenAPIConfig.BASE` property. * `ApiRequestOptions` now includes an optional `server` property, providing any path-level or operation-level server to requests. If specified, the provided value is used as base url instead of the `OpenAPIConfig.BASE` value in `getUrl()`. * Test cases now cover path-level or operation-level servers. * Test snapshots have been updated accordingly.
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
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.comas 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
serverproperty in theServiceandOperationinterfaces, which is set by the parser to the first server's URL in the corresponding Path Item Object or Operation Object (if available). Additionally, theApiRequestOptionstype now includes an optionalserverproperty 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.