openapi31: support 3.1+ reference metadata overrides#1215
Open
AlexanderWangY wants to merge 1 commit into
Open
openapi31: support 3.1+ reference metadata overrides#1215AlexanderWangY wants to merge 1 commit into
AlexanderWangY wants to merge 1 commit into
Conversation
Contributor
Author
|
|
AlexanderWangY
force-pushed
the
openapi31-reference-metadata
branch
from
04c4e37 to
79fca24
Compare
AlexanderWangY
force-pushed
the
openapi31-reference-metadata
branch
2 times, most recently
from
72d27bb to
614fc99
Compare
Contributor
Author
|
Rate limited in CI 🤣 |
fenollp
requested changes
Jul 9, 2026
Add summary and description support for OpenAPI 3.1 Reference Objects, reject those extra fields for OpenAPI 3.0, and regenerate the API documentation.
AlexanderWangY
force-pushed
the
openapi31-reference-metadata
branch
from
97348dc to
e562b6c
Compare
fenollp
requested changes
Jul 11, 2026
fenollp
left a comment
fenollp
left a comment
Collaborator
There was a problem hiding this comment.
LGTM. Some notes. Please rebase.
| wantDescription: "reference description", | ||
| }, | ||
| } { | ||
| t.Run(test.name, func(t *testing.T) { |
Collaborator
There was a problem hiding this comment.
Please add a t.Parallel()
| errMUSTSecurityScheme = errors.New("invalid securityScheme: value MUST be an object") | ||
| ) | ||
|
|
||
| // applyHeaderRefMetadata applies OpenAPI 3.1 overrides without mutating the referenced Header. |
Collaborator
There was a problem hiding this comment.
Unless I am mistaken, all these could mutate value directly. Also drop the comment line please.
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
2 participants
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.
Adds OpenAPI 3.1 Reference Object
summaryanddescriptionoverride support. This is described in the reference object spec.Changed ref.go and refs.tmpl to support new summary and description fields excluding Schema type.
These overrides do NOT apply in OpenAPI 3.0, and therefore are ignored. Furthermore, only the following Reference Object types support overrides:
These do not apply to CallbackRef or SchemaRef, as these fields are not allowed.
Some minor details to pay attention to:
Note: Updated the Issue #513 regression test because it previously treated description beside $ref as invalid in every version.
summaryanddescriptionare now recognized Reference Object fields and they override supported metadata in OAS 3.1 and are STILL ERRORS in OAS 3.0.Testing
Added regression testing in
loader_test.go.You can try it out!
Unrelated
CI was not having a fun time with the formatting after template generation. Instead, I changed
refsgenerator.goto feed the generated content into a formatter and then write to a file to preserve formatting. This is a purely cosmetic problem.