@redocly/cli 2.71.2 → 2.72.1

package/lib/eject-assets/generators/java/models.ts

@@ -0,0 +1,362 @@
+// Ejected from @redocly/client-generator@0.8.1 — the built-in "java" generator.
+// This file is yours: edit freely; the generated client stays machine-owned and is
+// rebuilt by `redocly generate-client`. Newer generator versions merge in with
+// `redocly eject-generator java --update`.
+// The `models` stage: named schemas as records with fromJson/toJson hydration,
+// wire-backed enums, and sealed union interfaces with a parse dispatcher — plus the
+// wire→typed value expressions the methods reuse.
+
+import {
+  type ApiModel,
+  type DateType,
+  deref,
+  discriminatorCases,
+  enumValues,
+  flattenAllOf,
+  type PropertyModel,
+  type SchemaModel,
+  uniqueIdentifiers,
+  unwrapNullable,
+} from '@redocly/client-generator';
+import { JavaPrinter } from '@redocly/client-generator/printers/java';
+
+import { JAVA, javaString, typeName } from './naming.ts';
+import { classify, isDateFormat, javaType } from './types.ts';
+
+/**
+ * Wire value → typed value expression over the runtime's JSON graph, or undefined when
+ * the raw `Object` is already the type. `depth` names the lambda parameters of nested
+ * collections (`item`, `item2`, …): Java rejects a lambda parameter that shadows one.
+ */
+export function hydration(
+  schema: SchemaModel,
+  expr: string,
+  model: ApiModel,
+  // Required on purpose: a defaulted `'string'` let a call site forget it, and the method
+  // then returned a raw string where its own signature declared `OffsetDateTime`.
+  dateType: DateType,
+  depth = 0
+): string | undefined {
+  const bare = unwrapNullable(schema);
+  switch (bare.kind) {
+    case 'scalar':
+      if (dateType === 'Date' && bare.scalar === 'string' && isDateFormat(bare)) {
+        return bare.metadata?.format === 'date'
+          ? `asLocalDate(${expr})`
+          : `asOffsetDateTime(${expr})`;
+      }
+      return `${SCALAR_READERS[bare.scalar]}(${expr})`;
+    case 'enum':
+      return `${SCALAR_READERS[bare.scalar]}(${expr})`;
+    case 'literal':
+      return `${SCALAR_READERS[typeof bare.value === 'string' ? 'string' : typeof bare.value === 'boolean' ? 'boolean' : 'number']}(${expr})`;
+    case 'omit':
+      return hydration({ kind: 'ref', name: bare.base }, expr, model, dateType, depth);
+    case 'ref': {
+      const kind = classify(bare.name, model);
+      if (kind === 'record') return `${typeName(bare.name)}.fromJson(${expr})`;
+      if (kind === 'enum') {
+        const reader = enumValues(deref(bare, model)!)!.scalar === 'string' ? 'asString' : 'asLong';
+        return `${typeName(bare.name)}.fromWire(${reader}(${expr}))`;
+      }
+      if (kind === 'union') return `parse${typeName(bare.name)}(${expr})`;
+      const target = deref(bare, model);
+      return target === undefined ? undefined : hydration(target, expr, model, dateType, depth);
+    }
+    case 'array':
+    case 'record': {
+      const item = depth === 0 ? 'item' : `item${depth + 1}`;
+      const inner =
+        hydration(
+          bare.kind === 'array' ? bare.items : bare.value,
+          item,
+          model,
+          dateType,
+          depth + 1
+        ) ?? item;
+      return `${bare.kind === 'array' ? 'asList' : 'asMap'}(${expr}, ${item} -> ${inner})`;
+    }
+    case 'union':
+    case 'null':
+    case 'object':
+    case 'intersection':
+    case 'unknown':
+      return undefined;
+  }
+}
+
+const SCALAR_READERS = {
+  string: 'asString',
+  integer: 'asLong',
+  number: 'asDouble',
+  boolean: 'asBoolean',
+};
+
+/** The record components may not collide with the record's own methods or the locals of fromJson/toJson. */
+// prettier-ignore
+const RECORD_MEMBER_SLOTS = [
+  'data', 'json', 'toJson', 'fromJson', 'hashCode', 'equals', 'toString', 'getClass', 'wait',
+  'notify', 'notifyAll', 'clone', 'finalize',
+];
+
+/** The sealed unions a record is a member of, so it declares `implements` for each. */
+function unionsOf(name: string, model: ApiModel): string[] {
+  const unions: string[] = [];
+  for (const candidate of model.schemas) {
+    if (classify(candidate.name, model) !== 'union') continue;
+    const cases = discriminatorCases(candidate.schema, model)!;
+    if (cases.cases.some((entry) => entry.schemaName === name)) {
+      unions.push(typeName(candidate.name));
+    }
+  }
+  return unions;
+}
+
+function writeRecord(
+  printer: JavaPrinter,
+  name: string,
+  properties: PropertyModel[],
+  model: ApiModel,
+  dateType: DateType,
+  description?: string
+): void {
+  // A response never carries a `writeOnly` property, and responses decode into this same
+  // record, so the property is optional even when the description requires it.
+  const fields = properties.map((property) =>
+    property.writeOnly ? { ...property, required: false } : property
+  );
+  const components = uniqueIdentifiers(
+    fields.map((property) => property.name),
+    { style: 'camel', reserved: JAVA, taken: RECORD_MEMBER_SLOTS }
+  );
+  const record = typeName(name);
+  const interfaces = ['JsonValue', ...unionsOf(name, model)];
+  printer.doc(record, description);
+  printer.block(
+    `public record ${record}(`,
+    () => {
+      fields.forEach((property, index) => {
+        const comma = index < fields.length - 1 ? ',' : '';
+        printer.line(`${javaType(property.schema, model, dateType)} ${components[index]}${comma}`);
+      });
+    },
+    `) implements ${interfaces.join(', ')} {`
+  );
+  printer.indent(() => {
+    printer.block(
+      `public static ${record} fromJson(Object json) {`,
+      () => {
+        printer.line('Map<String, Object> data = asObject(json);');
+        printer.block(
+          'if (data == null) {',
+          () => {
+            printer.line('return null;');
+          },
+          '}'
+        );
+        printer.block(
+          `return new ${record}(`,
+          () => {
+            fields.forEach((property, index) => {
+              const raw = `data.get(${javaString(property.name)})`;
+              const comma = index < fields.length - 1 ? ',' : '';
+              printer.line(`${hydration(property.schema, raw, model, dateType) ?? raw}${comma}`);
+            });
+          },
+          ');'
+        );
+      },
+      '}'
+    );
+    printer.blank();
+    printer.line('@Override');
+    printer.block(
+      'public Map<String, Object> toJson() {',
+      () => {
+        printer.line('Map<String, Object> data = new LinkedHashMap<>();');
+        fields.forEach((property, index) => {
+          const put = `data.put(${javaString(property.name)}, ${components[index]});`;
+          if (property.required) {
+            printer.line(put);
+          } else {
+            printer.block(
+              `if (${components[index]} != null) {`,
+              () => {
+                printer.line(put);
+              },
+              '}'
+            );
+          }
+        });
+        printer.line('return data;');
+      },
+      '}'
+    );
+  });
+  printer.line('}');
+  printer.blank();
+}
+
+function writeEnum(
+  printer: JavaPrinter,
+  name: string,
+  values: Array<string | number | boolean>,
+  scalar: 'string' | 'integer',
+  description?: string
+): void {
+  const enumName = typeName(name);
+  const wireType = scalar === 'string' ? 'String' : 'Long';
+  const members = enumValues({ kind: 'enum', values, scalar })!.memberNames;
+  printer.doc(enumName, description);
+  printer.block(
+    `public enum ${enumName} implements WireValue {`,
+    () => {
+      values.forEach((value, index) => {
+        const literal = typeof value === 'string' ? javaString(value) : `${value}L`;
+        printer.line(`${members[index]}(${literal})${index < values.length - 1 ? ',' : ';'}`);
+      });
+      printer.blank();
+      printer.line(`private final ${wireType} wire;`);
+      printer.blank();
+      printer.block(
+        `${enumName}(${wireType} wire) {`,
+        () => {
+          printer.line('this.wire = wire;');
+        },
+        '}'
+      );
+      printer.blank();
+      printer.line('@Override');
+      printer.block(
+        `public ${wireType} wire() {`,
+        () => {
+          printer.line('return wire;');
+        },
+        '}'
+      );
+      printer.blank();
+      printer.line(
+        '/** The member for a wire value; null for null, an exception for an unknown value. */'
+      );
+      printer.block(
+        `public static ${enumName} fromWire(${wireType} wire) {`,
+        () => {
+          printer.block(
+            'if (wire == null) {',
+            () => {
+              printer.line('return null;');
+            },
+            '}'
+          );
+          printer.block(
+            `for (${enumName} member : values()) {`,
+            () => {
+              printer.block(
+                'if (member.wire.equals(wire)) {',
+                () => {
+                  printer.line('return member;');
+                },
+                '}'
+              );
+            },
+            '}'
+          );
+          printer.line(`throw new IllegalArgumentException("Unknown ${enumName} value: " + wire);`);
+        },
+        '}'
+      );
+    },
+    '}'
+  );
+  printer.blank();
+}
+
+/** Write every named schema at the printer's current depth: records, enums, union dispatchers. */
+export function writeJavaModels(
+  printer: JavaPrinter,
+  model: ApiModel,
+  dateType: DateType = 'string'
+): void {
+  for (const { name, schema } of model.schemas) {
+    const asEnum = enumValues(schema);
+    if (asEnum !== undefined && (asEnum.scalar === 'string' || asEnum.scalar === 'integer')) {
+      writeEnum(printer, name, asEnum.values, asEnum.scalar, schema.description);
+      continue;
+    }
+    if (schema.kind === 'object' || schema.kind === 'intersection') {
+      const flat = flattenAllOf(schema, model);
+      if (flat !== undefined) {
+        writeRecord(
+          printer,
+          name,
+          flat.properties,
+          model,
+          dateType,
+          flat.description ?? schema.description
+        );
+        continue;
+      }
+    }
+    const cases = discriminatorCases(schema, model);
+    if (cases !== undefined) {
+      const union = typeName(name);
+      const sealed = classify(name, model) === 'union';
+      const table = cases.cases
+        .map((entry) => `${entry.value} -> ${typeName(entry.schemaName)}`)
+        .join(', ');
+      // The table carries the description's own values, so it goes through the comment escaper.
+      printer.doc(union, `A discriminated union on ${javaString(cases.property)}: ${table}.`);
+      if (sealed) {
+        // The permitted records sit in the same compilation unit, so `permits` is implied.
+        printer.line(`public sealed interface ${union} extends JsonValue {}`);
+        printer.blank();
+      }
+      // A target without a record of its own keeps the raw value, so the union is `Object`.
+      printer.block(
+        `public static ${sealed ? union : 'Object'} parse${union}(Object json) {`,
+        () => {
+          printer.line('Map<String, Object> data = asObject(json);');
+          printer.block(
+            'if (data == null) {',
+            () => {
+              printer.line('return null;');
+            },
+            '}'
+          );
+          printer.block(
+            `switch (String.valueOf(data.get(${javaString(cases.property)}))) {`,
+            () => {
+              for (const entry of cases.cases) {
+                const target = { kind: 'ref', name: entry.schemaName } as const;
+                const typed = hydration(target, 'data', model, dateType) ?? 'data';
+                printer.line(`case ${javaString(entry.value)}:`);
+                printer.indent(() => printer.line(`return ${typed};`));
+              }
+              printer.line('default:');
+              printer.indent(() =>
+                printer.line(
+                  sealed
+                    ? `throw new IllegalArgumentException("Unknown ${cases.property} value: " + data.get(${javaString(cases.property)}));`
+                    : 'return data;'
+                )
+              );
+            },
+            '}'
+          );
+        },
+        '}'
+      );
+      printer.blank();
+      continue;
+    }
+    // Everything else (plain unions, aliases, records) has no Java declaration;
+    // references resolve to the underlying type via javaType.
+  }
+}
+
+/** Render every named schema at depth 0 — the models section on its own, for the render bars. */
+export function renderJavaModels(model: ApiModel, dateType: DateType = 'string'): string {
+  const printer = new JavaPrinter();
+  writeJavaModels(printer, model, dateType);
+  return printer.toString();
+}

package/lib/eject-assets/generators/java/naming.ts

@@ -0,0 +1,135 @@
+// Ejected from @redocly/client-generator@0.8.1 — the built-in "java" generator.
+// This file is yours: edit freely; the generated client stays machine-owned and is
+// rebuilt by `redocly generate-client`. Newer generator versions merge in with
+// `redocly eject-generator java --update`.
+// The `naming` stage: the shared printer/naming instance, the string escaper, the
+// enclosing class name, and the collision-free type/member/method identifiers every
+// other stage builds on.
+
+import {
+  type ApiModel,
+  casing,
+  identifierFor,
+  NotSupportedError,
+  type OperationModel,
+  RESERVED_WORDS,
+} from '@redocly/client-generator';
+import { JavaPrinter } from '@redocly/client-generator/printers/java';
+import { JAVA_RUNTIME_SOURCE } from '@redocly/client-generator/runtime-sources';
+
+export const JAVA = RESERVED_WORDS.java;
+
+// Naming and escaping delegate to the printer — one implementation, one policy.
+export const naming = new JavaPrinter();
+
+/**
+ * The type names the runtime already uses inside the generated class — its own nested
+ * types and every JDK type it references, read off its source — plus the names the
+ * generated methods add. A schema that folds to one of them gets a `Model` suffix: a
+ * nested `record Config` would shadow the runtime's `Config`, and a nested `record Thread`
+ * (GitHub has one) would shadow `java.lang.Thread` for the runtime's retry sleep.
+ */
+const TAKEN_TYPE_NAMES = new Set([
+  ...[
+    // Comments, char literals (a `'"'` would otherwise open a string), then strings go.
+    ...JAVA_RUNTIME_SOURCE.replace(/\/\*[\s\S]*?\*\/|\/\/.*$/gm, '')
+      .replace(/'(?:[^'\\]|\\.)'/g, "''")
+      .replace(/"(?:[^"\\]|\\.)*"/g, '""')
+      .matchAll(/\b[A-Z][A-Za-z0-9]*\b/g),
+  ].map((match) => match[0]),
+  'Servers',
+  'Void',
+]);
+
+export function typeName(name: string): string {
+  const ident = naming.typeName(name);
+  return TAKEN_TYPE_NAMES.has(ident) ? `${ident}Model` : ident;
+}
+
+export function memberName(name: string): string {
+  return naming.memberName(name);
+}
+
+/** `"…"` with the escapes javac needs — safe for any spec-supplied text. */
+export function javaString(value: string): string {
+  return naming.string(value);
+}
+
+/**
+ * The enclosing class — Java puts one public class per file, named after it — derived
+ * from the `--output` stem the way Python derives its module name (`openapi.client` →
+ * `OpenapiClient`). A schema of the same name cannot nest inside it, so that is rejected
+ * with the fix rather than renamed behind the user's back.
+ */
+export function javaClassName(stem: string, model: ApiModel): string {
+  const name = identifierFor(stem, { style: 'pascal', reserved: JAVA });
+  // Inside a class named `Config` or `List`, those names mean the class itself.
+  if (TAKEN_TYPE_NAMES.has(name)) {
+    throw new NotSupportedError(
+      `The output file name "${stem}" gives the Java class the name "${name}", which the SDK already uses for one of its own types. Choose another --output name, for example "${stem}-sdk.ts".`
+    );
+  }
+  const clash = model.schemas.find((schema) => typeName(schema.name) === name);
+  if (clash !== undefined) {
+    throw new NotSupportedError(
+      `The output file name "${stem}" gives the Java class the same name as the "${clash.name}" schema, which cannot nest inside it. Choose another --output name, for example "${stem}-sdk.ts".`
+    );
+  }
+  return name;
+}
+
+/**
+ * The package clause the output declares, derived from the API title the way the PHP
+ * generator derives its namespace: the title's words in lowercase, run together, as Java
+ * package names are written (`Cafe Orders API` → `cafeordersapi`). A class in the default
+ * package cannot be imported from any named package, so there is always one. A name that
+ * cannot be a package as is follows Oracle's package-naming convention: a keyword gets a
+ * trailing underscore (`class_`), and so does `java`, which the JVM keeps for the JDK; a
+ * leading digit gets a leading underscore (`_3dprintingapi`).
+ */
+export function javaPackageName(title: string): string {
+  const plain = plainPackageName(title);
+  if (plain === '') return 'api';
+  if (/^[0-9]/.test(plain)) return `_${plain}`;
+  return JAVA.has(plain) || plain === 'java' ? `${plain}_` : plain;
+}
+
+/** The title's words in lowercase, run together — the package before any convention applies. */
+export function plainPackageName(title: string): string {
+  return casing.pascal(title).toLowerCase();
+}
+
+export function methodName(op: OperationModel): string {
+  return identifierFor(op.name, { style: 'camel', reserved: JAVA });
+}
+
+/** The methods every class inherits from `Object`; an operation named after one would override it. */
+// prettier-ignore
+const OBJECT_METHODS = [
+  'getClass', 'hashCode', 'equals', 'clone', 'toString', 'notify', 'notifyAll', 'wait',
+  'finalize',
+];
+
+/** The methods an operation may add beside its own, all named after it. */
+const METHOD_VARIANTS = ['', 'WithHeaders', 'Pages', 'Items'];
+
+/**
+ * The method name for every operation, unique across the client — two operationIds may
+ * camel-case to one name (`get-user`, `getUser`). Each name also books its `WithHeaders`,
+ * `Pages`, and `Items` variants, so a later operation named like one of them moves aside
+ * (`listOrdersPages2`). Keyed by the IR name, which the sanitizer already made unique.
+ */
+export function methodIdents(model: ApiModel): Map<string, string> {
+  const used = new Set(OBJECT_METHODS);
+  const idents = new Map<string, string>();
+  for (const op of model.services.flatMap((service) => service.operations)) {
+    const base = identifierFor(op.name, { style: 'camel', reserved: JAVA });
+    let ident = base;
+    for (let suffix = 2; METHOD_VARIANTS.some((variant) => used.has(ident + variant)); suffix++) {
+      ident = `${base}${suffix}`;
+    }
+    for (const variant of METHOD_VARIANTS) used.add(ident + variant);
+    idents.set(op.name, ident);
+  }
+  return idents;
+}