Skip to content

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

go-generator

Verified

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

FileKindSize
SKILL.mdskill md8.8 KB
---
name: go-generator
description: Design of the ejected Redocly `go` client generator. Read it, and update it, before changing generators/go/.
---

# The `go` generator — its skill

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

## What it emits

One self-contained `<stem>.go` (`package client`): structs with `json` tags, a `Client`
with one `(T, error)` method per operation taking a `context.Context`, and the embedded
runtime. Go ≥ 1.21, standard library only — zero dependencies.

## Design decisions that must hold

- **Models are structs**: required fields by value, optionals as pointers with
  `,omitempty`; the `json` tag always carries the exact wire name.
- **A `writeOnly` property is optional** even when required: requests and responses share
  one struct, and a response never carries it. A pointer with `,omitempty` still sends it
  in a request, and leaves it `nil` in a response instead of claiming a zero value.
- **Package clause:** `package client` by default, `goPackage` to override — a generated
  file usually lands in a package the consumer already owns. The value is checked against
  Go's own rule (lowercase letters, digits, `_`, no leading digit, not a keyword) and an
  invalid one fails generation: silently rewriting a publisher's package name would be
  worse than saying no.
- **Doc comments are gofmt's shape**, not the description's: a blank line prints as `//`
  (never `// `, which gofmt strips), and CONSECUTIVE blank lines collapse to one — gofmt
  rewrites `//\n//` to a single `//`, so emitting both means our output is not
  gofmt-clean. Descriptions with a double blank line are common in real specs.
- **Every parameter is its own argument, so their names share one namespace** with the
  arguments the method declares itself (`ctx`, `body`, `params`, and the receiver). Build them with
  `uniqueIdentifiers(..., { taken: … })`: OpenAPI lets one operation use a name in two
  locations (`id` in the path AND in the query), and Go rejects a duplicate parameter. The
  wire name is untouched, so the request is unchanged.
- **Naming:** exported PascalCase via `identifierFor` + an `N` prefix for digit-leading
  names (`3ds` → `N3ds` — an `_`-prefixed field is unexported and invisible to
  `encoding/json`); `+1`/`-1` become `Plus1`/`Minus1`.
- **Enums** are typed consts (`type Status string` + `StatusInProgress Status = …`);
  **discriminated unions** are `type X = any` plus a generated `UnmarshalX([]byte)`
  dispatcher; **allOf** is flattened.
- **Errors:** `(T, error)` returns ARE the error mode — `errorMode` does not change the
  output (the generator declares `errorModes: ['throw']`, so `result` fails fast).
  Non-2xx → `*APIError`; timeouts → `*TimeoutError`.
- **Dates:** `dateType: Date` maps `format: date-time` to `time.Time` (encoding/json
  handles RFC 3339 natively) and `date` to the runtime's `Date` wrapper, which
  marshals as `2006-01-02`. Query values format explicitly, never via `String()`.
- **Response headers:** an operation that DECLARES success-response headers gains a
  `<Op>WithHeaders(ctx, …) (T, <Op>Headers, error)` variant; `<Op>Headers` is a
  generated struct with pointer fields (nil when absent or unparsable), coerced to
  int64/bool/string. Operations without declared headers get no variant, and the
  base method stays `(T, error)`.
- **Servers:** when the description declares servers, one `<Name>URL(...)` function per
  server is emitted (named from the server description); server VARIABLES become string
  parameters (Go has no defaults — the doc comment states the spec default), so templated
  base URLs need no manual string building. The client's baked default stays `servers[0]`
  with variable defaults substituted.
- **Stream bodies pass through.** For an untyped `multipart/form-data` operation
  (`isUntypedMultipartBody` from the toolkit: a schema that is neither an object nor a
  `$ref`) or a binary operation (`isBinaryContentType`), the body argument is `any` and
  the runtime sorts it out (`multipartBody` / `binaryBody`): an `io.Reader` is the
  request body as is, with no `io.ReadAll` and exactly one attempt (a consumed reader
  cannot be replayed, whatever the retry policy says); a `[]byte` or a `string` is sent as
  bytes, not JSON-marshalled, and stays replayable, so retries stay; a map or struct body
  of an untyped multipart operation keeps the `toMultipart` path. The description's (or
  the multipart boundary's) `Content-Type` is applied only when the caller set none, so a
  forwarded boundary survives; that rule holds for every operation. The per-attempt
  timeout still applies. Typed multipart bodies are unaffected.
- **Parity surface:** auth, retries with `Retry-After` + jittered backoff, per-attempt
  `context.WithTimeout`, idempotency keys, middleware, pagination (`<Op>Pages`/`<Op>Items`
  as `func(yield func(T, error) bool)` — `range`-over-func needs Go ≥ 1.23; 1.21 calls
  them with a callback), SSE, multipart.
- **The EMITTED FILE is gofmt-clean, not just the runtime.** `gofmt -l` on generated
  output must print nothing, so the download is idiomatic as-is. The emitter earns that
  deterministically, without shelling out to `gofmt`:
  - `alignGoColumns` pads columns the way gofmt's tabwriter does — struct field types and
    tags, `const`/`var` types and `=`, and map-literal values — within each contiguous run.
    A line starting with a Go KEYWORD is a statement, never a declaration, and must never
    be padded (`case "x":` is not a field).
  - `case` sits at its `switch`'s own indent, so the switch body is not emitted as an
    indented block.
  - At most one blank line between declarations, none at end of file, and a blank line
    inside a doc comment is `//` — never `// ` with a trailing space.
    A change here is verified by the `gofmt -l` bar in the unit suite, at cafe AND
    large-description scale.
- The runtime is hand-written in `runtime/runtime.go` in this folder (gofmt-clean, `go vet`-clean)
  and embedded at prepare time.
  Under `--runtime module` it is written as a same-package `runtime.go` beside the client,
  whose import block then lists only the packages its own body uses.
- **`OnSettled` sees every sent call once.** `send()` calls each `Middleware.OnSettled` after
  the last attempt with a `SettledCall`: the operation id, the final response (body unread)
  or the error, the attempt count, and the duration from the first attempt to the end of the
  `OnResponse` hooks on the final response. A timeout is a `*TimeoutError`; a cancelled or
  expired caller context is an error that wraps `context.Canceled` or
  `context.DeadlineExceeded`. A call whose body cannot be encoded or read does not reach it,
  and a request that `http.NewRequestWithContext` cannot build settles with 1 attempt.
- **Telemetry is opt-in at generation time.** With `client.telemetry: on` the generator also
  writes `telemetry.go` (from `telemetry/telemetry.go` in this folder, embedded at prepare
  time) beside the client, in both runtime modes, with the client's package clause and the
  generator version baked in. The client file does not change. The application registers
  `NewUsageTelemetry(UsageTelemetryOptions{...}).Middleware()` and calls `Flush(ctx)` before
  it exits, because Go has no exit hook. An SDK owner calls `Register()` instead, in an `init`
  function, which adds the middleware to `registeredMiddleware` of the runtime, so `send` runs
  it for every client; `FlushUsageTelemetry(ctx)` then flushes each registered instance. The
  runtime declares `registeredMiddleware` in both modes, so the client file stays the same.
  Its exported names are reserved for every SDK, and
  every unexported name starts with `usageTelemetry`, because the file shares the package
  with the model types and the runtime.
- Authored ONLY with the neutral toolkit — the dogfooding guard fails otherwise.

- **It documents itself.** With `client.docs` (or `--docs`), the `docs` hook writes
  `<stem>.go.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`. Pagination on the page is decided by
  `paginationRuleFor`, the same helper this generator resolves pagination with.

## The modify loop

1. Edit this skill: state the new behavior or decision.
2. Make `generators/go/` 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 go --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: 322kUpdated 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: 198kUpdated 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: 198kUpdated 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: 198kUpdated Claude CodeCodexVerifiedInstall