OpenAPI 3.1 / JSON Schema 2020-12: $ref+description fix and further feature support - #382
Merged
jemacineiras merged 2 commits intoJul 24, 2026
Conversation
Up to standards ✅🟢 Issues
|
| Metric | Results |
|---|---|
| Complexity | 45 |
| Duplication | 0 |
NEW Get contextual insights on your PRs based on Codacy's metrics, along with PR and Jira context, without leaving GitHub. Enable AI reviewer
TIP This summary will be updated as you push new changes.
Follow-up to the $ref+description fix, addressing further 3.1 gaps found in an audit of the schema generator. Structural correctness fixes (narrow blast radius; only affect specs using these constructs): - $defs: collect top-level `$defs` as a schema source and resolve `$ref: '#/$defs/...'` (ApiTool.getComponentSchemas). Models under $defs now generate and are referenceable. - prefixItems / items:false: tuple arrays and `items:false` degrade to List<Object> instead of an empty/invalid element type. - type:"null": a scalar null type degrades to Object instead of emitting an invalid `null` Java type. - nullability: a field that is nullable (3.0 `nullable:true` or the 3.1 ["T","null"] idiom) is no longer marked required, so no spurious @NotNull is generated (ApiTool.isNullable). - patternProperties: an object with patternProperties maps to Map<String,V> instead of an empty POJO. - 3.1 binary strings: `contentEncoding` / `contentMediaType` are recognised as binary (MultipartFile), complementing `format: binary`. Adds regression test `testOpenApi31Completeness` covering all of the above. Documented limitations (left non-breaking, deferred as larger work): - multi-type unions still pick the first concrete type (tested behaviour; needs a real union type model); - description/summary/examples propagation (wide blast radius: 51 specs use field-level description); - contains/propertyNames/unevaluated*/dependent*/if-then-else validation (needs new validators; parsed-through today); - info.summary / license.identifier metadata; - $id/$anchor resolution and $schema/$dynamicRef (ignored non-fatally). Bumps version 6.4.2 -> 6.5.0 (new features). Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
joseegman-idoneea
force-pushed
the
feat/openapi31-completeness
branch
from
July 24, 2026 05:09
cd17035 to
e6cd4c9
Compare
Carry property-level `description` and `example` (3.0) / `examples` (3.1, first entry) into the generated model classes via the @Schema annotation. This also surfaces the sibling `description` of a `$ref` (OpenAPI 3.1), completing the earlier $ref+description fix. Values are Java-string-escaped in the template. - SchemaFieldObject gains `description`/`example`. - ApiTool.getDescription/getExample (examples[0] fallback). - ModelBuilder applies them at the property choke point (applyMetadata). - templateSchema.ftlh emits `description`/`example` on @Schema when present. Assets across the OpenAPI and AsyncAPI generators are regenerated accordingly. Note: the Lombok model template does not use @Schema, so descriptions are not emitted there (unchanged). Full multiapi-engine suite: 110/110 passing (mvn clean test). Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
This was referenced Jul 24, 2026
jemacineiras
approved these changes
Jul 24, 2026
jemacineiras
added
bug
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.
Builds on #381 (already merged into
main) and adds further OpenAPI 3.1 / JSON Schema 2020-12 support found while auditing the schema generator.Structural correctness fixes
$defsschema source#/$defs/*unresolved → NPE / missing modelprefixItems/items: falseList<Object>type: "null"nullJava typeObjectnullable:trueor["T","null"])@NotNullon a nullable field@NotNullpatternPropertiesMap<String, V>contentEncoding/contentMediaType)StringMultipartFiledescription+example/examples@Schema(incl. the$refsiblingdescription)The
description/example(examples) propagation applies to both the OpenAPI and AsyncAPI model generators; committed assets are regenerated accordingly. The Lombok model template does not use@Schema, so descriptions are not emitted there (unchanged).Tests
New regression
testOpenApi31Completenessexercises$defs,prefixItems,type:"null", the nullable-but-required case,patternProperties,contentEncoding, plusdescription/example/examplesin one spec. Fullmultiapi-enginesuite: 110/110 passing (mvn clean test).Documented limitations (non-breaking, deferred as larger work)
["string","integer"]) still pick the first concrete type — the current tested behaviour; a real union type model is a separate feature.Version bump
6.4.2→6.5.0(new features).🤖 Generated with Claude Code