Redocly/redocly-cli / packages/client-generator/eject-assets/skills/go-generator
go-generator
UnverifiedDesign 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; thejsontag always carries the exact wire name. -
A
writeOnlyproperty is optional even when required: requests and responses share one struct, and a response never carries it. A pointer with,omitemptystill sends it in a request, and leaves itnilin a response instead of claiming a zero value. -
Package clause:
package clientby default,goPackageto 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 withuniqueIdentifiers(..., { taken: … }): OpenAPI lets one operation use a name in two locations (idin 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+ anNprefix for digit-leading names (3ds→N3ds— an_-prefixed field is unexported and invisible toencoding/json);+1/-1becomePlus1/Minus1. -
Enums are typed consts (
type Status string+StatusInProgress Status = …); discriminated unions aretype X = anyplus a generatedUnmarshalX([]byte)dispatcher; allOf is flattened. -
Errors:
(T, error)returns ARE the error mode —errorModedoes not change the output (the generator declareserrorModes: ['throw'], soresultfails fast). Non-2xx →*APIError; timeouts →*TimeoutError. -
Dates:
dateType: Datemapsformat: date-timetotime.Time(encoding/json handles RFC 3339 natively) anddateto the runtime'sDatewrapper, which marshals as2006-01-02. Query values format explicitly, never viaString(). -
Response headers: an operation that DECLARES success-response headers gains a
<Op>WithHeaders(ctx, …) (T, <Op>Headers, error)variant;<Op>Headersis 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 staysservers[0]with variable defaults substituted. -
Stream bodies pass through. For an untyped
multipart/form-dataoperation (isUntypedMultipartBodyfrom the toolkit: a schema that is neither an object nor a$ref) or a binary operation (isBinaryContentType), the body argument isanyand the runtime sorts it out (multipartBody/binaryBody): anio.Readeris the request body as is, with noio.ReadAlland exactly one attempt (a consumed reader cannot be replayed, whatever the retry policy says); a[]byteor astringis sent as bytes, not JSON-marshalled, and stays replayable, so retries stay; a map or struct body of an untyped multipart operation keeps thetoMultipartpath. The description's (or the multipart boundary's)Content-Typeis 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-attemptcontext.WithTimeout, idempotency keys, middleware, pagination (<Op>Pages/<Op>Itemsasfunc(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 -lon generated output must print nothing, so the download is idiomatic as-is. The emitter earns that deterministically, without shelling out togofmt:alignGoColumnspads columns the way gofmt's tabwriter does — struct field types and tags,const/vartypes 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).casesits at itsswitch'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 thegofmt -lbar in the unit suite, at cafe AND large-description scale.
-
The runtime is hand-written in
runtime/runtime.goin this folder (gofmt-clean,go vet-clean) and embedded at prepare time. Under--runtime moduleit is written as a same-packageruntime.gobeside the client, whose import block then lists only the packages its own body uses. -
OnSettledsees every sent call once.send()calls eachMiddleware.OnSettledafter the last attempt with aSettledCall: 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 theOnResponsehooks on the final response. A timeout is a*TimeoutError; a cancelled or expired caller context is an error that wrapscontext.Canceledorcontext.DeadlineExceeded. A call whose body cannot be encoded or read does not reach it, and a request thathttp.NewRequestWithContextcannot build settles with 1 attempt. -
Telemetry is opt-in at generation time. With
client.telemetry: onthe generator also writestelemetry.go(fromtelemetry/telemetry.goin 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 registersNewUsageTelemetry(UsageTelemetryOptions{...}).Middleware()and callsFlush(ctx)before it exits, because Go has no exit hook. An SDK owner callsRegister()instead, in aninitfunction, which adds the middleware toregisteredMiddlewareof the runtime, sosendruns it for every client;FlushUsageTelemetry(ctx)then flushes each registered instance. The runtime declaresregisteredMiddlewarein both modes, so the client file stays the same. Its exported names are reserved for every SDK, and every unexported name starts withusageTelemetry, 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), thedocshook 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 ownsamplehook, so the page can only show the syntax of the SDK beside it, and the layout comes fromrenderReferencePagein the authoring toolkit — reachable from an ejected copy through@redocly/client-generator. Pagination on the page is decided bypaginationRuleFor, the same helper this generator resolves pagination with.
The modify loop
- Edit this skill: state the new behavior or decision.
- Make
generators/go/match it. - Run
redocly generate-clientand inspect thegit diffof the generated output — generated files are never hand-edited.
Newer built-in versions merge in with redocly eject-generator go --update.
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| 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: 319k | Updated | Claude CodeCodex | Verified | Install |
| 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: 196k | Updated | Claude CodeCodex | Verified | Install |
| 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: 196k | Updated | Claude CodeCodex | Verified | Install |
| 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: 196k | Updated | Claude CodeCodex | Verified | Install |