Support references in Components Object entries #454
Merged
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.
Fixes #377
Breaking Changes
Components Object
There are changes for the
OpenAPIKit30module (OAS 3.0.x specification) inthis section.
Entries in the Components Object's
responses,parameters,examples,requestBodies,headers,securitySchemes,links, andcallbacksdictionaries have all gained support for references. Note that
pathItemsandschemasstill do not support references (per the specification), thoughschemascan be JSON references by their very nature already.This change fixes a gap in OpenAPIKit's ability to represent valid documents.
If you are using subscript access or
lookup()functions to retrieve entriesfrom the Components Object, you do not need to change that code. These
functions have learned how to follow references they encounter until they land
on the type of entity being looked up. If you want the behavior of just
doing a regular lookup and passing the result back even if it is a reference,
you can use the new
lookupOnce()function. The existinglookup()functionscan now throw an error they would never throw before:
ReferenceCycleError.Error message phrasing has changed subtly which is unlikely to cause problems
but if you have tests that compare exact error messages then you may need to
update the test expectations.
If you construct
Componentsin-code then you have two options. You can swapout existing calls to the
Componentsinit()initializer with calls to thenew
Components.direct()convenience constructor or you can nest each componententry in an
Eitherlike follows:If your code uses the
staticopenAPIComponentsKeyPathvariable on types thatcan be found in the Components Object (likely very uncommon), you will now need
to handle two possibilities: the key path either refers to an object (of generic
type
T) or it refers to anEither<OpenAPI.Reference<T>, T>.