feat: generate @Deprecated annotations for spec-level deprecation (Java/Spring/Docs) - #1283
Open
jjjasper wants to merge 4 commits into
Open
feat: generate @Deprecated annotations for spec-level deprecation (Java/Spring/Docs)#1283jjjasper wants to merge 4 commits into
jjjasper wants to merge 4 commits into
Conversation
Wire x-deprecated and x-sunset-date vendor extensions from OpenAPI info block into generated Java/Spring code, marking the entire API as deprecated with a sunset date message in Javadoc when present. - New DeprecationExtensions utility mirrors B015 lint rule parsing - BoatJavaCodeGen and BoatSpringCodeGen propagate spec-level deprecation through preprocessOpenAPI, fromOperation, postProcessModelProperty, and postProcessAllModels hooks - Message text appended to @deprecated Javadoc tags and @Schema descriptions - Unit tests for DeprecationExtensions boolean/date parsing and message building - Mustache templates updated to render deprecation message when x-boat-deprecation-message is present in vendorExtensions Co-Authored-By: Claude <noreply@anthropic.com>
Add BoatSpringCodeGenTests.shouldGenerateDeprecationAnnotationsFromSpecLevel() and BoatCommonJavaCodeGenTests.shouldGenerateDeprecationAnnotationsFromSpecLevel() to verify @deprecated annotations and sunset-date messages are generated when x-deprecated and x-sunset-date are present in the OpenAPI info block. Add deprecated-spec.yaml test fixture with: - Info-level x-deprecated and x-sunset-date - Operation-level deprecated: true - Property-level deprecated: true Co-Authored-By: Claude <noreply@anthropic.com>
Add preprocessOpenAPI override to BoatDocsGenerator to compute spec-level deprecation and sunset-date message, then propagate to fromOperation hook similar to codegen classes. Update boat-docs templates to render deprecation message: - index.mustache: show message in the deprecated badge for operations - param.mustache: show message in the deprecated badge for parameters Co-Authored-By: Claude <noreply@anthropic.com>
…son templates postProcessAllModels previously checked `instanceof CodegenModel` against the top-level Map<String, Object>, whose entries are actually ModelsMap -> List<ModelMap> -> CodegenModel on openapi-generator 7.20.0. As written it was also a compile error (name clash on erasure with the real generic override), so this code path never ran and was never exercised by CI. Also fixes boat-java's default okhttp-gson library, which has its own api.mustache/pojo.mustache overriding the ones under boat-java/ that were edited for this feature, so the deprecation message never rendered for the default boat-java output. Co-Authored-By: Claude <noreply@anthropic.com>
jjjasper
changed the title
|
jjjasper
changed the title
jjjasper
requested review from
AnjBB72,
afsinka-backbase,
bbzurek and
walaniam
September 4, 2026 09:19
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.
Summary
Generate
@Deprecatedannotations (and a deprecation message) across the Java, Spring, and docs generators when an OpenAPI spec is marked deprecated viainfo.x-deprecated(optionally withinfo.x-sunset-date).DeprecationExtensions(boat-scaffold/.../codegen/utils): readsx-deprecated/x-sunset-dateoffInfoand builds a human-readable deprecation message (e.g. "This API is deprecated and will be removed on 2026-12-31.").BoatJavaCodeGen/BoatSpringCodeGen: when the spec is marked deprecated, propagateisDeprecated/deprecatedand the message (via ax-boat-deprecation-messagevendor extension) onto every generated operation, model, and model property.BoatDocsGenerator: same propagation for the generated HTML docs, surfaced inboat-docs/index.mustacheandparam.mustache.@deprecatedtags and@Schema/@ApiModelannotations, for bothboat-java(root templates and theokhttp-gsonlibrary templates, which is the default library and has its own copies) andboat-spring.DeprecationExtensions, and end-to-end codegen tests (BoatCommonJavaCodeGenTests,BoatSpringCodeGenTests) against a newdeprecated-spec.yamlfixture.Fix included in this PR
While validating the feature, found
postProcessAllModelsinBoatJavaCodeGen/BoatSpringCodeGennever actually ran: it checkedinstanceof CodegenModelagainst the wrong map nesting level (openapi-generator 7.20.0 nests asMap<String, ModelsMap>→List<ModelMap>→CodegenModel), and as originally written was a compile error (generic-erasure name clash), meaning this branch had never been built or test-run. Also foundBoatJavaCodeGen's defaultokhttp-gsonlibrary templates (which take precedence over the rootboat-javatemplates that were edited) never got the message rendering, and one Javadoc-parsing test that was fragile to a pre-existing blank-line quirk in generated code. All fixed and covered by the passing test suite below.Test plan
mvn -pl boat-scaffold -am test(JDK 17) — full boat-scaffold module test suite passes, includingBoatCommonJavaCodeGenTests#shouldGenerateDeprecationAnnotationsFromSpecLevel,BoatSpringCodeGenTests#shouldGenerateDeprecationAnnotationsFromSpecLevel, andDeprecationExtensionsTests🤖 Generated with Claude Code