Skip to content

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

go-generator

Unverified

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: 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