@redocly/client-generator 0.3.8 → 0.4.0

package/eject-assets/generators/go/index.ts

@@ -0,0 +1,336 @@
+// Ejected from @redocly/client-generator@0.4.0 — the built-in "go" 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 go --update`.
+// The built-in `go` generator — the second non-TypeScript library entry,
+// authored with the language-neutral toolkit only (same dogfooding invariant as
+// the python generator, pinned by its guard test). Output is a single
+// stdlib-only Go file: structs with json tags, typed-const enums, discriminated
+// unions with unmarshal dispatchers, and a Client over the embedded runtime.
+// One file per pipeline stage (ADR-0020); this entry assembles them.
+
+import {
+  type ApiModel,
+  type CodeSample,
+  type DateType,
+  type EmitOptions,
+  type Generator,
+  identifierFor,
+  jsonSuccessSchema,
+  type NeutralPaginationRule,
+  type OperationModel,
+  paginationItemSchema,
+  renderReferencePage,
+  type SampleContext,
+  sseResponse,
+} from '@redocly/client-generator';
+import { exported, GoPrinter } from '@redocly/client-generator/printers/go';
+import { GO_RUNTIME_SOURCE } from '@redocly/client-generator/runtime-sources';
+
+import { writeGoServers } from './client.ts';
+import { goPaginationLiteral, goSecurityLiteral } from './descriptor.ts';
+import { renderGoModels } from './models.ts';
+import { GO, goOperationIdents, goPackageName, naming } from './naming.ts';
+import { writeGoMethod } from './operations.ts';
+import { writeGoPaginationWrappers } from './pagination.ts';
+import { goType } from './types.ts';
+
+export { renderGoModels } from './models.ts';
+export { goType } from './types.ts';
+
+/** Strip the package clause and import lines/blocks so a section stitches into one file. */
+function stripHeader(source: string): string {
+  const lines = source.split('\n');
+  const out: string[] = [];
+  let inImportBlock = false;
+  for (const line of lines) {
+    if (line.startsWith('package ')) continue;
+    if (line.startsWith('import (')) {
+      inImportBlock = true;
+      continue;
+    }
+    if (inImportBlock) {
+      if (line.startsWith(')')) inImportBlock = false;
+      continue;
+    }
+    if (line.startsWith('import ')) continue;
+    out.push(line);
+  }
+  return out.join('\n').trim();
+}
+
+/** Every stdlib package the merged inline file needs (the runtime dominates the list). */
+const GO_STDLIB_IMPORTS = [
+  'bytes',
+  'context',
+  'encoding/base64',
+  'encoding/json',
+  'errors',
+  'fmt',
+  'io',
+  'math/rand',
+  'mime/multipart',
+  'net/http',
+  'net/url',
+  'strconv',
+  'strings',
+  'time',
+];
+
+/**
+ * Everything below the import block: models, servers, the (optionally embedded)
+ * runtime, the operations table, and the Client — one emission path for both
+ * runtime modes, so module mode cannot drift from the inline layout.
+ */
+function writeGoBody(
+  printer: GoPrinter,
+  model: ApiModel,
+  emit: EmitOptions,
+  dateType: DateType,
+  paginationRules: Map<string, NeutralPaginationRule>,
+  embedRuntime: boolean
+): void {
+  printer.line(stripHeader(renderGoModels(model, dateType)));
+  printer.blank();
+  writeGoServers(printer, model);
+  if (embedRuntime) {
+    printer.line('// ─── Embedded runtime (@redocly/client-generator go runtime) ───');
+    printer.line(stripHeader(GO_RUNTIME_SOURCE));
+    printer.blank();
+  }
+
+  printer.block(
+    'type operationMeta struct {',
+    () => {
+      printer.line('ID         string');
+      printer.line('Method     string');
+      printer.line('Path       string');
+      printer.line('Security   [][]SecuritySpec');
+      printer.line('Pagination *PaginationSpec');
+    },
+    '}'
+  );
+  printer.blank();
+  printer.block(
+    'var operations = map[string]operationMeta{',
+    () => {
+      for (const { op, ident } of goOperationIdents(model)) {
+        const id = op.specName ?? op.name;
+        const security = goSecurityLiteral(op, model);
+        const rule = paginationRules.get(ident);
+        const fields = [
+          `ID: ${naming.string(id)}`,
+          `Method: ${naming.string(op.method.toUpperCase())}`,
+          `Path: ${naming.string(op.path)}`,
+          ...(security !== undefined ? [`Security: ${security}`] : []),
+          ...(rule !== undefined ? [`Pagination: ${goPaginationLiteral(rule)}`] : []),
+        ];
+        printer.line(`${naming.string(id)}: {${fields.join(', ')}},`);
+      }
+    },
+    '}'
+  );
+  printer.blank();
+
+  // Per-operation query-parameter structs (pointer fields: absent = not sent).
+  for (const { op, ident } of goOperationIdents(model)) {
+    if (op.queryParams.length === 0) continue;
+    printer.block(
+      `type ${ident}Params struct {`,
+      () => {
+        for (const param of op.queryParams) {
+          const fieldType = goType(param.schema, dateType);
+          printer.line(
+            `${exported(param.name)} ${fieldType.startsWith('*') ? fieldType : `*${fieldType}`}`
+          );
+        }
+      },
+      '}'
+    );
+    printer.blank();
+  }
+
+  printer.doc('Client', `Client for ${model.title} (${model.version}).`);
+  printer.block(
+    'type Client struct {',
+    () => {
+      printer.line('config Config');
+    },
+    '}'
+  );
+  printer.blank();
+  printer.block(
+    'func New(config Config) *Client {',
+    () => {
+      printer.block(
+        'if config.ServerURL == "" {',
+        () => {
+          printer.line(
+            `config.ServerURL = ${naming.string(emit.serverUrl ?? model.serverUrl ?? '')}`
+          );
+        },
+        '}'
+      );
+      printer.line('return &Client{config: config}');
+    },
+    '}'
+  );
+  printer.blank();
+
+  for (const { op, ident } of goOperationIdents(model)) {
+    writeGoMethod(printer, op, ident, dateType);
+    if (sseResponse(op) === undefined && (op.successResponseHeaders?.length ?? 0) > 0) {
+      writeGoMethod(printer, op, ident, dateType, model, true);
+    }
+    const rule = paginationRules.get(ident);
+    if (rule === undefined) continue;
+    const success = jsonSuccessSchema(op);
+    const pageType = success === undefined ? 'any' : goType(success, dateType);
+    const element = paginationItemSchema(success, rule.items, model);
+    writeGoPaginationWrappers(
+      printer,
+      op,
+      ident,
+      dateType,
+      pageType,
+      element === undefined ? 'any' : goType(element, dateType)
+    );
+  }
+}
+
+/** The whole generated file: models + embedded runtime + operations table + Client. */
+export const goGenerator: Generator = ({ model, output, banner, emit, pagination }) => {
+  const printer = new GoPrinter();
+  const dateType = emit.dateType ?? 'string';
+  const packageName = goPackageName(emit.goPackage);
+  // Pagination arrives RESOLVED from the pipeline — one fit-verified answer per run.
+  const paginationRules = new Map<string, NeutralPaginationRule>();
+  for (const { op, ident } of goOperationIdents(model)) {
+    const spec = pagination?.get(op.name)?.spec;
+    if (spec !== undefined) paginationRules.set(ident, spec);
+  }
+  printer.line(
+    `// Code generated by @redocly/client-generator (go) from "${model.title}" ${model.version}. DO NOT EDIT.`
+  );
+  printer.line(
+    '// Regenerate with `redocly generate-client`. Standard library only — zero dependencies.'
+  );
+  printer.line(`package ${packageName}`);
+  printer.blank();
+  const embedRuntime = emit.runtime !== 'module';
+  // One merged import block. Inline: the runtime uses every entry. Module: the runtime
+  // imports for itself, so the client lists only the packages its own body references —
+  // an unused import is a Go compile error, so the subset is derived from the body text.
+  const imports = embedRuntime
+    ? GO_STDLIB_IMPORTS
+    : (() => {
+        const scratch = new GoPrinter();
+        writeGoBody(scratch, model, emit, dateType, paginationRules, false);
+        const body = scratch.toString();
+        return GO_STDLIB_IMPORTS.filter((spec) =>
+          new RegExp(`\\b${spec.split('/').pop()}\\.`).test(body)
+        );
+      })();
+  printer.block(
+    'import (',
+    () => {
+      for (const spec of imports) {
+        printer.line(naming.string(spec));
+      }
+    },
+    ')'
+  );
+  printer.blank();
+
+  writeGoBody(printer, model, emit, dateType, paginationRules, embedRuntime);
+
+  const entry = {
+    path: output.path.replace(/\.[^.\\/]+$/, '.go'),
+    // Sections are stitched with their own trailing blanks; gofmt allows at most one
+    // between declarations and none at the end of the file.
+    content: printer.toString(),
+  };
+  if (embedRuntime) return [entry];
+  // The runtime, verbatim except the package clause — same directory, same Go package.
+  const header = banner.map((line) => `// ${line}`).join('\n');
+  const runtimeSource = GO_RUNTIME_SOURCE.replace(/^package .*$/m, `package ${packageName}`);
+  return [
+    entry,
+    {
+      path: entry.path.replace(/[^\\/]+$/, 'runtime.go'),
+      content: `${header}\n${runtimeSource.trimEnd()}\n`,
+    },
+  ];
+};
+
+/** One idiomatic Go call per operation — feeds `x-codeSamples` for docs. */
+export function goSample(op: OperationModel, ctx: SampleContext): CodeSample {
+  const dateType = ctx.emit.dateType ?? 'string';
+  // `goPackage` renames the package clause, and the snippet qualifies with it.
+  const pkg = ctx.emit.goPackage ?? 'client';
+  // The DEDUPED name: on a collision the method is `GetUser2`, and a snippet naming the
+  // raw `GetUser` would show a call that goes to a different operation.
+  const ident =
+    goOperationIdents(ctx.model).find((entry) => entry.op.name === op.name)?.ident ??
+    exported(op.name);
+  const args = [
+    'ctx',
+    ...op.pathParams.map(
+      (param) => `"<${identifierFor(param.name, { style: 'camel', reserved: GO })}>"`
+    ),
+    ...(op.requestBody ? [`${goType(op.requestBody.schema, dateType)}{ /* … */ }`] : []),
+    ...(op.queryParams.length > 0 ? ['nil'] : []),
+  ];
+  // The assignment matches the return shape: an SSE method returns one iterator, a void
+  // method returns `error` alone — `result, err :=` would not compile against either.
+  const call = `client.${ident}(${args.join(', ')})`;
+  const statement =
+    sseResponse(op) !== undefined
+      ? `stream := ${call}`
+      : jsonSuccessSchema(op) === undefined
+        ? `err := ${call}`
+        : `result, err := ${call}`;
+  return {
+    lang: 'go',
+    label: 'Go SDK',
+    source: `client := ${pkg}.New(${pkg}.Config{})\n${statement}\n`,
+  };
+}
+
+/**
+ * The SDK's own reference page, written when `client.docs` is on. The call snippets come
+ * from `goSample` — this generator's own hook — so the page can only ever show the syntax
+ * of the SDK beside it, and ejecting this generator takes the page with it.
+ */
+export const goDocs: Generator = ({ model, output, emit, pagination }) => [
+  {
+    path: output.path.replace(/\.[^.\\/]+$/, '.go.md'),
+    content: renderReferencePage(model, {
+      title: `${model.title} Go SDK reference`,
+      frontmatter: emit.docsFrontmatter === true,
+      language: {
+        name: 'go',
+        label: 'Go',
+        fence: 'go',
+        requires: 'The SDK needs the standard library only.',
+      },
+      sample: (op) => goSample(op, { model, emit, outputPath: output.path }),
+      paginated: new Set(pagination?.keys() ?? []),
+    }),
+  },
+];
+
+export default {
+  name: 'go',
+  run: goGenerator,
+  sample: goSample,
+  docs: goDocs,
+  errorModes: ["throw"],
+  notApplicable: {
+    "outputMode": "it always emits one self-contained file",
+    "runtime": "the runtime is always embedded in the generated file",
+    "argsStyle": "inputs follow the target language's own idiom",
+    "importExt": "the generated file has no relative imports"
+  },
+  requiresGenerator: '^0.4.0',
+};

package/eject-assets/generators/go/models.ts

@@ -0,0 +1,179 @@
+// Ejected from @redocly/client-generator@0.4.0 — the built-in "go" 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 go --update`.
+// The `models` stage: named schemas as typed-const enums, structs with json tags
+// (allOf flattened), and discriminated unions with unmarshal dispatchers.
+
+import {
+  type ApiModel,
+  casing,
+  type DateType,
+  discriminatorCases,
+  enumValues,
+  flattenAllOf,
+  type PropertyModel,
+} from '@redocly/client-generator';
+import { exported, GoPrinter } from '@redocly/client-generator/printers/go';
+
+import { naming } from './naming.ts';
+import { goType } from './types.ts';
+
+function writeStruct(
+  printer: GoPrinter,
+  name: string,
+  properties: PropertyModel[],
+  dateType: DateType,
+  description?: string
+): void {
+  printer.doc(exported(name), description);
+  printer.block(
+    `type ${exported(name)} struct {`,
+    () => {
+      for (const property of properties) {
+        const field = exported(property.name);
+        let fieldType = goType(property.schema, dateType);
+        let tag = `\`json:"${property.name}"\``;
+        if (!property.required) {
+          if (
+            !fieldType.startsWith('*') &&
+            !fieldType.startsWith('[]') &&
+            !fieldType.startsWith('map[') &&
+            fieldType !== 'any'
+          ) {
+            fieldType = `*${fieldType}`;
+          }
+          tag = `\`json:"${property.name},omitempty"\``;
+        }
+        printer.line(`${field} ${fieldType} ${tag}`);
+      }
+    },
+    '}'
+  );
+  printer.blank();
+}
+
+/** Render every named schema: typed-const enums, structs (allOf flattened), union dispatchers. */
+export function renderGoModels(model: ApiModel, dateType: DateType = 'string'): string {
+  const printer = new GoPrinter();
+  printer.line('package client');
+  printer.blank();
+  const needsJSON = model.schemas.some(
+    ({ schema }) => discriminatorCases(schema, model) !== undefined
+  );
+  if (needsJSON) {
+    printer.line('import "encoding/json"');
+    printer.blank();
+  }
+  // The models section also compiles standalone (see the unit bars), so it declares
+  // its own `time` import when a field is a date.
+  const body = renderGoModelBodies(model, dateType);
+  if (dateType === 'Date' && body.includes('time.Time')) {
+    printer.line('import "time"');
+    printer.blank();
+  }
+  printer.line(body);
+  return printer.toString();
+}
+
+/** The struct/enum/union declarations themselves — the header is renderGoModels' job. */
+function renderGoModelBodies(model: ApiModel, dateType: DateType): string {
+  const printer = new GoPrinter();
+
+  for (const { name, schema } of model.schemas) {
+    const asEnum = enumValues(schema);
+    if (asEnum !== undefined) {
+      const base = asEnum.scalar === 'string' ? 'string' : 'int64';
+      printer.doc(exported(name), schema.description);
+      printer.line(`type ${exported(name)} ${base}`);
+      printer.blank();
+      printer.block(
+        'const (',
+        () => {
+          // Two values may fold to one pascal name (`1.5` and `15`) — a duplicate const
+          // would not compile, so the names are made unique per enum. A digit-leading
+          // value needs no `_` prefix here: the member starts with the type name.
+          const used = new Set<string>();
+          asEnum.values.forEach((value) => {
+            const base = casing.pascal(String(value)) || 'Value';
+            let suffix = '';
+            for (let n = 2; used.has(base + suffix); n++) suffix = String(n);
+            used.add(base + suffix);
+            const member = exported(name) + base + suffix;
+            printer.line(`${member} ${exported(name)} = ${naming.literal(value)}`);
+          });
+        },
+        ')'
+      );
+      printer.blank();
+      continue;
+    }
+    if (schema.kind === 'object' || schema.kind === 'intersection') {
+      const flat = flattenAllOf(schema, model);
+      if (flat !== undefined) {
+        writeStruct(
+          printer,
+          name,
+          flat.properties,
+          dateType,
+          flat.description ?? schema.description
+        );
+        continue;
+      }
+    }
+    const cases = discriminatorCases(schema, model);
+    if (cases !== undefined) {
+      const typeName = exported(name);
+      const table = cases.cases
+        .map((entry) => `${entry.value} -> ${exported(entry.schemaName)}`)
+        .join(', ');
+      printer.line(`// ${typeName} is a discriminated union ("${cases.property}"): ${table}.`);
+      printer.line(`type ${typeName} = any`);
+      printer.blank();
+      printer.line(
+        `// Unmarshal${typeName} decodes into the member selected by "${cases.property}".`
+      );
+      printer.block(
+        `func Unmarshal${typeName}(data []byte) (${typeName}, error) {`,
+        () => {
+          printer.block(
+            'var probe struct {',
+            () => {
+              printer.line(`Discriminant string \`json:"${cases.property}"\``);
+            },
+            '}'
+          );
+          printer.block(
+            'if err := json.Unmarshal(data, &probe); err != nil {',
+            () => {
+              printer.line('return nil, err');
+            },
+            '}'
+          );
+          // gofmt keeps `case` at the switch's own indent, so the switch body is NOT
+          // indented as a block — only each case's statements are.
+          printer.line('switch probe.Discriminant {');
+          for (const entry of cases.cases) {
+            printer.block(`case ${naming.string(entry.value)}:`, () => {
+              printer.line(`var value ${exported(entry.schemaName)}`);
+              printer.line('err := json.Unmarshal(data, &value)');
+              printer.line('return value, err');
+            });
+          }
+          printer.line('}');
+          printer.line('var fallback any');
+          printer.line('err := json.Unmarshal(data, &fallback)');
+          printer.line('return fallback, err');
+        },
+        '}'
+      );
+      printer.blank();
+      continue;
+    }
+    // Everything else (plain unions, scalar aliases, records) becomes a type alias.
+    printer.doc(exported(name), schema.description);
+    printer.line(`type ${exported(name)} = ${goType(schema, dateType)}`);
+    printer.blank();
+  }
+  return printer.toString();
+}

package/eject-assets/generators/go/naming.ts

@@ -0,0 +1,49 @@
+// Ejected from @redocly/client-generator@0.4.0 — the built-in "go" 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 go --update`.
+// The `naming` stage: the shared printer/naming instance, the package clause, and
+// the collision-free operation identifiers every other stage builds on.
+
+import {
+  type ApiModel,
+  NotSupportedError,
+  type OperationModel,
+  RESERVED_WORDS,
+} from '@redocly/client-generator';
+import { exported, GoPrinter } from '@redocly/client-generator/printers/go';
+
+// One escaping policy for every Go string literal this generator prints.
+export const naming = new GoPrinter();
+
+export const GO = RESERVED_WORDS.go;
+
+/**
+ * The package clause the output declares. Rewriting an invalid name would hide the
+ * publisher's typo behind a package their imports don't mention, so this rejects it.
+ */
+export function goPackageName(configured: string | undefined): string {
+  if (configured === undefined) return 'client';
+  if (!/^[a-z_][a-z0-9_]*$/.test(configured) || GO.has(configured)) {
+    throw new NotSupportedError(
+      `goPackage "${configured}" is not a valid Go package name: use lowercase letters, digits, and underscores, don't start with a digit, and avoid Go keywords.`
+    );
+  }
+  return configured;
+}
+
+/** Every operation with its collision-free exported Go method name. */
+export function goOperationIdents(model: ApiModel): Array<{ op: OperationModel; ident: string }> {
+  const used = new Set<string>();
+  const out: Array<{ op: OperationModel; ident: string }> = [];
+  for (const service of model.services) {
+    for (const op of service.operations) {
+      let ident = exported(op.name);
+      let suffix = 2;
+      while (used.has(ident)) ident = `${exported(op.name)}${suffix++}`;
+      used.add(ident);
+      out.push({ op, ident });
+    }
+  }
+  return out;
+}