feat(java): annotate endpoint availability in generated SDK

[Swimburger]

Description

Mirrors the TypeScript SDK generator's getAvailabilityDocs behavior in both Java generators. Generated client methods (v1) and generated reference.md (v2) now reflect the IR availability field.

Mapping per AvailabilityStatus:

• DEPRECATED → v1: @Deprecated annotation + @deprecated[ message] Javadoc tag; v2: @deprecated[ message] appended to reference.md description
• IN_DEVELOPMENT → @beta This endpoint is in development and may change.[ message]
• PRE_RELEASE → @beta This endpoint is in pre-release and may change.[ message]
• GENERAL_AVAILABILITY → nothing extra

Changes Made

generators/java/ (v1 — client class generation)

• New helper AvailabilityUtils in generators/java/generator-utils/ exposing getAvailabilityDocs(...) and isDeprecated(...).
• AbstractEndpointWriter.generate() now emits the endpoint docs first and appends the availability Javadoc after them (Javadoc block tags must follow the main description), and applies @Deprecated to every method variant it builds (default, no-request-options, no-request-body, body-only, byte-array, and all 4 file-upload input-stream overloads).
• SyncDelegatingHttpEndpointMethodSpecs / AsyncDelegatingHttpEndpointMethodSpecs now copy methodSpec.annotations alongside javadoc so @Deprecated propagates to the delegating client methods.
• Changelog entry under generators/java/sdk/changes/unreleased/.

generators/java-v2/ (reference.md generation)

Java v2 does not generate SDK client classes (those remain v1's responsibility per generators/java-v2/CLAUDE.md), but it owns reference.md. The helper is mirrored in TypeScript (can't literally share code with v1, which is Java) to keep wording identical.

• New generators/java-v2/sdk/src/utils/getAvailabilityDocs.ts — TS port of the helper returning the same @deprecated / @beta strings as the TS SDK helper.
• buildReference.ts now prepends the endpoint docs (if any) and appends the availability string (if any) as the description for EndpointReference, so deprecated / beta endpoints are surfaced in the generated reference.md.
• Unit test in src/utils/__test__/getAvailabilityDocs.test.ts covering every AvailabilityStatus variant with and without a message.

Testing

• v1: Unit tests added in AvailabilityUtilsTest covering each AvailabilityStatus variant with and without a message, plus isDeprecated cases.
• v2: Unit tests added for getAvailabilityDocs (8 cases) — passing via vitest run.
• ./gradlew spotlessApply and ./gradlew :generator-utils:test :sdk:compileJava pass.
• pnpm format run in generators/java-v2/sdk.

Reviewer notes / things worth a close look

• Seed/snapshot regeneration was NOT run — any Java seed fixture whose IR carries an availability field would produce a diff now (both v1 client methods and v2 reference.md). If snapshots should be refreshed as part of this PR, please flag and I'll regenerate.
• v2 renders raw @deprecated / @beta strings in markdown — matches the exact TS-SDK wording per the task spec, but if you'd prefer a markdown-native rendering (e.g. **Deprecated:** …) let me know.
• Breadth of @Deprecated application (v1) — the annotation is added on every MethodSpec.Builder created inside AbstractEndpointWriter.generate() (including all file-upload / byte-array overloads). Worth double-checking I didn't miss one or apply it somewhere a delegating layer won't see it.
• Javadoc ordering (v1) — endpoint docs are emitted first, then availability block tags (@deprecated / @beta), to satisfy Javadoc's rule that block tags follow the main description. This addresses earlier Devin Review feedback on ordering.
• Code sharing between v1 and v2 — v1 helper is in Java, v2 helper is in TypeScript (mirrored); they can't literally share a module across the language boundary, but the wording and branch logic are intentionally identical.
• Prettier diff in buildReference.ts — most of the diff is a prettier reflow (2-space indentation) applied by pnpm format against the file; the functional change is the getEndpointReferenceDescription helper and the import.
• The v1 helper uses availability.getStatus().getEnumValue() so an unknown future enum value falls through to Optional.empty() / non-deprecated rather than throwing.

Link to Devin session: https://app.devin.ai/sessions/d0e161353b3141408ae79073dc3af055
Requested by: @Swimburger

---

[devin-ai-integration]

🤖 Devin AI Engineer

I'll be helping with this pull request! Here's what you should know:

✅ I will automatically:

• Address comments on this PR. Add '(aside)' to your comment to have me ignore it.
• Look at CI failures and help fix them

Note: I can only respond to comments from users who have write access to this repository.

⚙️ Control Options:

• Disable automatic comment and CI monitoring

[claude]

Claude Code Review

This repository is configured for manual code reviews. Comment @claude review to trigger a review and subscribe this PR to future pushes, or @claude review once for a one-time review.

_{Tip: disable this comment in your organization's Code Review settings.}

[github-actions]

SDK Generation Benchmark Results

Comparing PR branch against latest nightly baseline on main (2026-04-17T04:58:39Z).

Full benchmark table (click to expand)

Generator	Spec	main (generator)	main (E2E)	PR (generator)	Delta
java-sdk	square	170s	187s	124s	-46s (-27.1%)

main (generator): generator-only time via --skip-scripts (includes Docker image build, container startup, IR parsing, and code generation — this is the same Docker-based flow customers use via fern generate). main (E2E): full customer-observable time including build/test scripts (nightly baseline, informational). Delta is computed against generator-only baseline.
⚠️ = generation exited with a non-zero exit code (timing may not reflect a successful run).
Baseline from nightly runs on main (latest: 2026-04-17T04:58:39Z). Trigger benchmark-baseline to refresh.
Last updated: 2026-04-17 20:34 UTC