clientgen

Documentation

Overview

Package clientgen generates a self-contained, dependency-free typed Go client from a tyche-produced OpenAPI 3.x document.

The generated module imports only the standard library: it emits its own copy of the request/response types (option "B" — no dependency on the server package), one method per operation, and bakes in tyche's conventions — the {"data": …} success envelope and the application/problem+json error shape (surfaced as a typed *APIError).

Types are recovered from the document by walking each operation's (inlined) schemas and deduplicating by structural identity, so shapes that also appear as named entries in components.schemas collapse to a single clean Go type. Set Options.TypeNamingStrategy to TypeNamingOperationScoped when distinct operations should generate distinct Go types even if their schemas are structurally identical.

Typical use is via the `tyche client` command; Generate is the programmatic entry point:

doc, _ := clientgen.ParseDocument(specJSON)
res, _ := clientgen.Generate(doc, clientgen.Options{
	Module: "github.com/yourco/gateway/client",
})
for _, f := range res.Files { os.WriteFile(filepath.Join(outDir, f.Name), f.Content, 0o644) }

Server-Sent Events operations (text/event-stream) generate a streaming method returning a typed *Stream[Event], iterated with the scanner pattern. Event name, ID, and retry metadata are available from the most recent event.

Index

• type AdditionalProperties
  • func (a *AdditionalProperties) UnmarshalJSON(b []byte) error
• type Components
• type Document
  • func ParseDocument(data []byte) (*Document, error)
• type File
• type Info
• type MediaType
• type Operation
• type Options
• type Parameter
• type PathItem
• type RequestBody
• type Response
• type Result
  • func Generate(doc *Document, opts Options) (*Result, error)
• type Schema
• type TypeNamingStrategy

Types

type AdditionalProperties

type AdditionalProperties struct {
	Bool   *bool
	Schema *Schema
}

AdditionalProperties models the JSON Schema additionalProperties keyword, which may be a boolean or a schema.

func (*AdditionalProperties) UnmarshalJSON

func (a *AdditionalProperties) UnmarshalJSON(b []byte) error

type Components

type Components struct {
	Schemas map[string]*Schema `json:"schemas"`
}

type Document

type Document struct {
	Paths      map[string]*PathItem `json:"paths"`
	Components *Components          `json:"components"`
	Info       Info                 `json:"info"`
	OpenAPI    string               `json:"openapi"`
}

Document is the subset of an OpenAPI 3.x document that the client generator consumes. It is intentionally self-contained (rather than reusing the server openapi types) so parsing is robust — most importantly so additionalProperties can be a schema or a boolean.

func ParseDocument

func ParseDocument(data []byte) (*Document, error)

ParseDocument decodes an OpenAPI document from JSON.

type File

type File struct {
	Name    string
	Content []byte
}

File is a generated output file (relative path + contents).

type Info

type Info struct {
	Title       string `json:"title"`
	Version     string `json:"version"`
	Description string `json:"description"`
}

type MediaType

type MediaType struct {
	Schema *Schema `json:"schema"`
}

type Operation

type Operation struct {
	RequestBody *RequestBody         `json:"requestBody"`
	Responses   map[string]*Response `json:"responses"`
	OperationID string               `json:"operationId"`
	Summary     string               `json:"summary"`
	Description string               `json:"description"`
	Tags        []string             `json:"tags"`
	Parameters  []*Parameter         `json:"parameters"`
	Deprecated  bool                 `json:"deprecated"`
}

type Options

type Options struct {
	// Module is the Go module path of the generated client (required), e.g.
	// "github.com/yourco/gateway/client". The generated go.mod uses it.
	Module string
	// Package is the package name for the generated files. Defaults to a
	// sanitized last segment of Module, or "client".
	Package string
	// GoVersion is the go directive written to go.mod. Defaults to "1.22".
	GoVersion string
	// ClientName is the generated client type name. Defaults to "Client".
	ClientName string
	// TypeNamingStrategy controls whether structurally identical schemas share
	// one generated Go type or receive operation-scoped names. The zero value
	// preserves the historical structural deduplication behaviour.
	TypeNamingStrategy TypeNamingStrategy
}

Options configures client generation.

type Parameter

type Parameter struct {
	Schema      *Schema `json:"schema"`
	Name        string  `json:"name"`
	In          string  `json:"in"`
	Description string  `json:"description"`
	Required    bool    `json:"required"`
}

type PathItem

type PathItem struct {
	Get     *Operation `json:"get"`
	Put     *Operation `json:"put"`
	Post    *Operation `json:"post"`
	Delete  *Operation `json:"delete"`
	Options *Operation `json:"options"`
	Head    *Operation `json:"head"`
	Patch   *Operation `json:"patch"`
	Trace   *Operation `json:"trace"`
}

type RequestBody

type RequestBody struct {
	Content     map[string]*MediaType `json:"content"`
	Description string                `json:"description"`
	Required    bool                  `json:"required"`
}

type Response

type Response struct {
	Headers     map[string]*Parameter `json:"headers"`
	Content     map[string]*MediaType `json:"content"`
	Description string                `json:"description"`
}

type Result

type Result struct {
	Files   []File
	Notices []string // non-fatal generation notes (e.g. unsupported schema features)
}

Result is the output of Generate.

func Generate

func Generate(doc *Document, opts Options) (*Result, error)

Generate produces a self-contained, dependency-free Go client module from an OpenAPI document.

type Schema

type Schema struct {
	Properties           map[string]*Schema    `json:"properties"`
	AdditionalProperties *AdditionalProperties `json:"additionalProperties"`
	Items                *Schema               `json:"items"`
	Description          string                `json:"description"`
	Ref                  string                `json:"$ref"`
	Format               string                `json:"format"`
	Type                 string                `json:"type"`
	Required             []string              `json:"required"`
	Enum                 []any                 `json:"enum"`
	AllOf                []*Schema             `json:"allOf"`
	OneOf                []*Schema             `json:"oneOf"`
	AnyOf                []*Schema             `json:"anyOf"`
	Nullable             bool                  `json:"nullable"`
}

Schema is the subset of JSON Schema / OpenAPI schema the generator understands.

type TypeNamingStrategy

type TypeNamingStrategy int

TypeNamingStrategy controls how generated schema types are named and reused.

const (
	// TypeNamingStructural deduplicates schemas by structural identity. When a
	// shape also appears under components.schemas, that component name is used.
	TypeNamingStructural TypeNamingStrategy = iota
	// TypeNamingOperationScoped gives each operation body/output/event context
	// its own generated type, even when another operation has an identical
	// schema shape.
	TypeNamingOperationScoped
)