Skip to content

Redocly/redocly-cli / packages/client-generator/eject-assets/skills/java-generator

java-generator

Unverified

Design of the ejected Redocly `java` client generator. Read it, and update it, before changing generators/java/.

The java generator — its skill

This file is the DESIGN of your ejected java generator (generators/java/): to change the generator, edit this skill first, then make the code match it — a diff to generators/java/ that has no covering sentence here is incomplete.

What it emits

One self-contained <Stem>.java: a public final class named after the output stem in PascalCase (client.ts → Client.java, openapi.client.ts → OpenapiClient.java), because Java puts one public class per file and names the file after it. The class nests the model records, the enums, the union interfaces, the embedded runtime, and one typed method per operation. Java ≥ 17 (records, sealed interfaces, instanceof patterns), HTTP over java.net.http.HttpClient, JSON over the runtime's own reader/writer — zero dependencies. The package derives from the API title the way the PHP namespace does: lowercase words run together (Cafe Orders API → package cafeordersapi;), because a class in the default package cannot be imported from any named package. A title that cannot be a package as is follows Oracle's package-naming convention — a keyword, or java, which the JVM keeps for the JDK, gets a trailing underscore (java_, class_); a leading digit gets a leading underscore (_3dprintingapi); a title with no usable letters becomes api — and the run warns with the package it used, since the reader cannot see it in the title. The generator takes no options; a different package is a change to javaPackageName in an ejected copy.

Design decisions that must hold

  • JSON is hand-written in the runtime. Java has no standard JSON library, and a dependency on one would break the zero-dependency story the other SDKs keep. Json.parse reads into a plain graph — Map<String, Object> (insertion ordered), List<Object>, String, Long for integral numbers, Double for the rest, Boolean, null — and Json.write serializes that graph plus the generated types: a JsonValue by its toJson(), a WireValue by its wire literal, a date by its ISO-8601 text. No streaming parse: a body is read whole, then parsed.
  • Models are records implementing the runtime's JsonValue. Every component is a reference type (Long, not long), so an optional or nullable value is simply null and a response that omits a required field hydrates instead of crashing. Hydration is compile-time generated per record — static X fromJson(Object json) reads each wire name through the runtime's null-tolerant readers (asString, asLong, asList(…, item -> …), Order.fromJson, Status.fromWire, parsePet), and toJson() returns a Map<String, Object> of the components (nulls skipped for optionals) that Json.write serializes recursively. No reflection. omit schemas hydrate through their base record.
  • A writeOnly property is optional even when required: requests and responses share one record, and a response never carries it.
  • Enums are Java enums implementing WireValue: members in SCREAMING_SNAKE (the toolkit's enumValues names, unique per enum) carrying the wire literal — a String or a Long — with wire() and fromWire(…), which returns null for null and throws IllegalArgumentException for an unknown value. Only string and integer enums get a type; other scalars stay their wire type.
  • Discriminated unions whose mapping targets are all records become a sealed interface X extends JsonValue that each member record implements, so a consumer narrows with instanceof patterns; parseX(Object json) dispatches on the discriminator and throws IllegalArgumentException for an unknown value, since a sealed type has no raw member. permits is implied: the members sit in the same compilation unit. A union with a target that has no record of its own is typed Object, and its parseX returns the raw map for an unknown value. Undiscriminated unions, inline objects, and intersections that do not flatten are Object. allOf is flattened.
  • Types: String/Long/Double/Boolean, List<T>, Map<String, T>, record and enum names, Object for everything untyped. Under dateType: Date, date-time is OffsetDateTime and date is LocalDate; hydration goes through asOffsetDateTime / asLocalDate, and the writer formats a date-time with ISO_OFFSET_DATE_TIME so the seconds never drop out (OffsetDateTime.toString() omits them when zero).
  • Reserved type names get a Model suffix. Everything nests in one class, so a schema named like a runtime type (Config, Envelope) or a JDK type the runtime references (Thread, List) would shadow it: naming.ts reads those names off the runtime source and renames the schema (ConfigModel). A schema named like the enclosing class itself cannot nest in it at all, and an enclosing class named like a runtime type (an --output of config.ts) would make that name mean the class, so both runs fail with the fix (another --output name).
  • Naming: types PascalCase, components and methods camelCase via identifierFor(..., RESERVED_WORDS.java); a reserved word gets a trailing underscore (class_), +1/-1 become plus1/minus1, and a digit-leading name gets _. Method names are unique across the client (getUser, getUser2), never one of Object's methods (getClass becomes getClass2), and each name books its WithHeaders, Pages, and Items variants, so a later operation named like one of them moves aside too.
  • Hand-built comments go through printer.doc, never a raw /** … */ line: a server description or a discriminator value may carry */ or \u, which end or break a Java comment. printer.doc writes */ as *&#47; and every backslash as \u005c, the escape of a backslash, which javac turns back into one without starting another escape — so the Javadoc reads exactly as the description does.
  • Every path parameter is its own argument, so their names share one namespace with the locals the method declares itself (body, params, op, query, url, …). Build them with uniqueIdentifiers(..., { taken: … }): a parameter named body becomes body2, and the wire name is untouched. Query parameters travel in a <Op>Params class — one nullable public field per parameter with a fluent setter of the same name (new ListOrdersParams().limit(50L)) — because Java has no named arguments; null for the whole class sends none. An array parameter repeats the key per element.
  • Method shape: path parameters first, the body next (Object for an untyped multipart or a binary operation), then <Op>Params when the operation has query parameters. A JSON success returns its type, a non-JSON success (PDF, image, octet stream) returns byte[], a bodiless success is void, and an SSE operation returns Iterable<ServerSentEvent>.
  • The operation literal is built where it is used — Operation op = new Operation(id, method, path, security, pagination) at the top of each method — never a static table of every operation: a single static initializer of a large description (GitHub: ~1000 operations) exceeds the JVM's 64 KB method size.
  • Errors: unchecked exceptions ARE the error mode. ApiException (status, url, decoded body) for a non-2xx response, ApiTimeoutException when an attempt exceeds the configured timeout, UncheckedIOException for a transport failure; errorMode does not change the output (the generator declares errorModes: ['throw'], so result fails fast).
  • Config is a fluent class: serverUrl, httpClient (an HTTP/1.1 client by default — the JDK default's h2c upgrade attempt confuses servers that do not speak HTTP/2), header(name, value) for every request (a Content-Type here wins over the description's, matched case-insensitively, so the header is never sent twice), timeout per attempt, retry (Retry: retries extra attempts, default 0; delay; strategy fixed or exponential; noJitter; retryOn replacing the default predicate), middleware (onRequest(HttpRequest.Builder) before each attempt, onResponse in reverse order), idempotencyKey supplier for POST/PATCH, and auth (Auth: bearer, basic, apiKey per scheme, each a value or a Supplier resolved per request).
  • Response headers: an operation that DECLARES success-response headers gains a <op>WithHeaders() variant returning Envelope<T> (data, headers — coerced to Long/Double/Boolean/String under camelCase keys, absent or unparsable values omitted — and status); a bodiless operation returns Envelope<Void>. Operations without declared headers get no variant.
  • Pagination: a paginated operation gains <op>Pages() and <op>Items(), both Iterable<T> over the runtime's iterPages, hydrated per page or item through mapIterable / flattenItems. Each iterator() starts a fresh request sequence.
  • Servers: when the description declares servers, a Servers class is emitted with one static method per server; server VARIABLES become String arguments, and the description's defaults live in the method's doc comment (Java has no default arguments). The client's baked default stays servers[0] with variable defaults substituted.
  • Stream bodies pass through. For an untyped multipart/form-data operation or a binary operation the body is Object and the runtime sorts it out (multipartBody / binaryBody): an InputStream is sent chunked, in exactly one attempt, whatever the retry policy says, because a consumed stream cannot be replayed; a byte[] or String is sent raw and keeps the retry policy; a map or a record of an untyped multipart operation is encoded with toMultipart; any other value of a binary operation is JSON-encoded. The caller's Content-Type (a Config header) wins over the description's or the multipart boundary's.
  • Parity surface: auth OR-alternatives, retries with Retry-After + full-jitter backoff, per-attempt timeouts, idempotency keys, middleware, pagination, SSE (iterSse with Last-Event-ID reconnect and the server's retry hint; auth resolves inside the opener, so each reconnect asks a token supplier again), multipart, and the X-Redocly-Client header.
  • The runtime is hand-written in runtime/Runtime.java in this folder, an abstract class Runtime that compiles on its own (javac --release 17 -Xlint:all -Werror) and is embedded at prepare time. Inline, the generator copies its class body into the generated class; under --runtime module it writes the same source as <Stem>Runtime.java, a public abstract class the client extends, so every runtime name resolves unqualified in both modes and the two cannot drift. Package-private members stay reachable because both classes share one package.
  • Authored ONLY with the neutral toolkit — the dogfooding guard fails otherwise.
  • It documents itself. With client.docs (or --docs), the docs hook writes <stem>.java.md: the security schemes, then one section per operation with its parameters, body, response type, and behavior notes. The call snippets come from this generator's own sample hook, so the page can only show the syntax of the SDK beside it, and the layout comes from renderReferencePage in the authoring toolkit — reachable from an ejected copy through @redocly/client-generator.

The modify loop

  1. Edit this skill: state the new behavior or decision.
  2. Make generators/java/ match it.
  3. Run redocly generate-client and inspect the git diff of the generated output — generated files are never hand-edited.

Newer built-in versions merge in with redocly eject-generator java --update.

brainstormingobra/superpowersYou MUST use this before any creative work - creating features, building components, adding functionality, modifying behavior, or planning anything new, in software or out of it (a talk, a business, a renovation).Stars: 319kUpdated Claude CodeCodexVerifiedInstall
brand-guidelinesanthropics/skillsApplies Anthropic's official brand colors and typography to any sort of artifact that may benefit from having Anthropic's look-and-feel. Use it when brand colors or style guidelines, visual formatting, or company design standards apply.Stars: 196kUpdated Claude CodeCodexVerifiedInstall
frontend-designanthropics/skillsGuidance for distinctive, intentional visual design when building new UI or reshaping an existing one. Helps with aesthetic direction, typography, and making choices that don't read as templated defaults.Stars: 196kUpdated Claude CodeCodexVerifiedInstall
mcp-builderanthropics/skillsGuide for creating high-quality MCP (Model Context Protocol) servers that enable LLMs to interact with external services through well-designed tools. Use when building MCP servers to integrate external APIs or services, whether in Python (FastMCP) or Node/TypeScript (MCP SDK).Stars: 196kUpdated Claude CodeCodexVerifiedInstall