feat: add support for OpenAPI Overlay#1727
Merged
jamietanna merged 2 commits intomainfrom Aug 20, 2024
Merged
Conversation
3869afb to
56f7dd4
Compare
71545d6 to
86a2575
Compare
86a2575 to
a694fae
Compare
In the past, users wishing to override specific configuration, for instance taking advantage of extensions such as `x-go-type` would need to modify the OpenAPI specification they are using. In a lot of cases, this OpenAPI specification would be produced by a different team to the consumers (or even a different company) and so asking them to make changes like this were unreasonable. This would lead to the API consumers needing to vendor the specification from the producer (which is our recommendation anyway) and then make any number of local changes to the specification to make it generate code that looks reasonable. However, in the case that a consumer would update their specification, they would likely end up with a number of merge conflicts. With these changes, it is now possible to make changes to the input OpenAPI specification _without needing to modify it directly_. This takes advantage of the OpenAPI Overlay specification[0], which is a stable specification, and is ready for wider implementation. This uses Speakeasy's implementation, which is noted as an "alpha" implementation. We introduce a new function, `LoadSwaggerWithOverlay`, which performs the wrangling of the Overlay on top of the specification we're pointing to, and make sure we wire in the ability to configure the path, as well as whether we want to relax the "strict" validation the Overlay library provides. Closes #1553. [0]: https://github.com/OAI/Overlay-Specification
As part of #1553. This tries to cover a lot of the more complex cases. Plus a fair bit of blurb + info to the README too.
a694fae to
f060f3b
Compare
This file contains hidden or 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
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.
In the past, users wishing to override specific configuration, for
instance taking advantage of extensions such as
x-go-typewould needto modify the OpenAPI specification they are using.
In a lot of cases, this OpenAPI specification would be produced by a
different team to the consumers (or even a different company) and so
asking them to make changes like this were unreasonable.
This would lead to the API consumers needing to vendor the specification
from the producer (which is our recommendation anyway) and then make any
number of local changes to the specification to make it generate code
that looks reasonable.
However, in the case that a consumer would update their specification,
they would likely end up with a number of merge conflicts.
With these changes, it is now possible to make changes to the input
OpenAPI specification without needing to modify it directly.
This takes advantage of the OpenAPI Overlay specification0, which is a
stable specification, and is ready for wider implementation.
This uses Speakeasy's implementation, which is noted as an "alpha"
implementation.
We introduce a new function,
LoadSwaggerWithOverlay, which performsthe wrangling of the Overlay on top of the specification we're pointing
to, and make sure we wire in the ability to configure the path, as well
as whether we want to relax the "strict" validation the Overlay library
provides.
Closes #1553.