fix(codegen): read singular example under 3.1 - #2523
Open
bendrucker wants to merge 1 commit into
Open
Conversation
describeWithExamples read only schema.Examples when the document was 3.1, returning early when that array was empty. OpenAPI 3.1 keeps the singular example keyword as a valid annotation and specs written against 3.1 use it heavily, so every such example was dropped from the generated doc comments. kin-openapi parses example into schema.Example regardless of document version, so the value was present and simply unread. Prefer the plural array when set and fall back to the singular value, which makes 3.1 output match 3.0 for the same input.
Contributor
Greptile SummaryThis PR restores singular
Confidence Score: 5/5The PR appears safe to merge with no actionable defects identified. The fallback preserves existing OpenAPI 3.0 behavior, keeps plural examples preferred under 3.1, and changes only generated documentation plus the fixture field introduced to test it.
|
| Filename | Overview |
|---|---|
| pkg/codegen/schema.go | Implements the OpenAPI 3.1 singular-example fallback without changing generated API shapes. |
| pkg/codegen/schema_test.go | Covers nil input, both version branches, precedence, absent examples, and structured rendering. |
| internal/test/openapi31/spec.yaml | Adds a singular-example property to the existing OpenAPI 3.1 fixture. |
| internal/test/openapi31/openapi31_test.go | Verifies the fixture retains its description and emits the singular example comment. |
| internal/test/openapi31/openapi31.gen.go | Contains only the expected generated field and documentation output. |
Reviews (1): Last reviewed commit: "fix(codegen): read singular example unde..." | Re-trigger Greptile
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
1 participant
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.
Under OpenAPI 3.1, every
example:in a spec is dropped from the generated doc comments.describeWithExamplesbranches on the document version. The 3.1 arm reads onlyschema.Examples, the plural JSON Schema array, and returns the description unchanged when that array is empty, never falling back to the singular value. OpenAPI 3.1 keepsexampleas a valid annotation, and specs written against 3.1 still use it heavily, so the singular keyword generates nothing at all.Regenerating a real 3.1 spec showed the size of it: 380
// Example:comments on the 3.0 path, 0 on the 3.1 path.The two paths are mirror images. Neither reads both keywords:
exampleexampleskin-openapi's schema unmarshalling has no version branch, so
example:lands inschema.Exampleunder 3.1 exactly as it does under 3.0. The value is parsed and present, just never read. That makes this a fallback in the codegen rather than anything to do with loading.Change
Prefer
schema.Exampleswhen it's set and fall back toschema.Example, so 3.1 output matches 3.0 for the same input.This only adds comments where the current code emits none. No types, names, or signatures move. Consumers regenerating against it see doc comments appear and nothing else change.
Scope
The symmetric change would be reading plural
exampleson the 3.0 path, which I left out.examplesisn't a valid schema keyword in 3.0, so honoring it would invent comments from input that shouldn't be there, and it would churn checked-in generated files for every existing 3.0 user. The 3.1 direction has neither cost. It's a small change in the same function if you'd rather have the symmetry.Tests
internal/test/openapi31/spec.yamlgains aPet.nicknameproperty using the singular keyword.TestPetExampleCommentsparses the generated source and asserts the comment, so the regression fails the suite if it comes back.TestDescribeWithExamplescovers the version branches directly, including 3.1 preferring the plural array when a schema carries both keywords.