GitHub Releases NuGet v1.0.0 MIT

metaengine-openapi-go-nethttp

OpenAPI 3.x → idiomatic Go: schema-driven structs (json:"…" tags, pointers for optional fields) and a net/http client with context.Context-first methods returning (T, error), Go doc comments, bearer/basic auth, retries, timeouts, and HTTP-status error handling (>= 400 → typed *HTTPStatusError, ErrNullResponse sentinel). Shipped as a single self-contained binary — no .NET runtime required.

OpenAPI 3.xMetaEngine IRGo · net/http
Try the interactive converter
Install

Pick your registry

The same generator, published to every ecosystem we support. Install however your project expects.

GitHub ReleasesPrimarygithub.com/meta-engine/metaengine-openapi-go-nethttp
$go install github.com/meta-engine/metaengine-openapi-go-nethttp@latest
v1.0.0
NuGetMetaEngine.Go.OpenApi.NetHttp
$dotnet add package MetaEngine.Go.OpenApi.NetHttp
v1.0.0
Usage

Drive it from the CLI or programmatically

GitHub Releases ships a zero-config CLI. NuGet ships the same generator as a C# fluent API — same options, same output.

GitHub Releases · go install / brew · CI-friendly

After install, point the CLI at your schema. It writes the generated tree to your chosen output directory.

Basic syntax
terminal
metaengine-openapi-go-nethttp <input> <output> <module> <package> [flags]

Supports OpenAPI 3.0+ specifications in both JSON and YAML formats. A single self-contained binary — no .NET runtime required. <module> is the Go module path (e.g. github.com/acme/api); <package> is the generated Go package name (e.g. client).

Quick examples
Generate from a local file
metaengine-openapi-go-nethttp api.yaml ./client github.com/acme/api client
Generate from a URL
metaengine-openapi-go-nethttp https://api.example.com/openapi.json ./client github.com/acme/api client
With doc comments, error handling and retries
metaengine-openapi-go-nethttp api.yaml ./client github.com/acme/api client \
  --documentation \
  --error-handling \
  --retries 3 \
  --include-tags pets,store
CLI options
Option
Description
--documentation
Generate Go doc comments
--options-threshold <n>
Use an options struct for methods with more than n parameters
--validate-struct-tags
Add validate struct tags to generated models
--timeout <seconds>
Set the HTTP client timeout
--base-url-env <name>
Read the base URL from this environment variable at runtime
--bearer-auth <env>
Add bearer-token auth; the token is read from this environment variable
--bearer-header <name>
Use a custom header name for the bearer token (with --bearer-auth)
--basic-auth <userEnv:passEnv>
Add basic auth; username/password read from these environment variables
--retries [n]
Retry failed requests, optionally capping at n attempts
--header <name:env>
Add a custom request header sourced from an environment variable (repeatable)
--middleware
Generate a request/response middleware hook on the client
--error-handling
Map HTTP error status codes to Go errors (>= 400 → typed *HTTPStatusError)
--throw-for <codes>
Return a formatted error (HTTP <code>: <body>) for these status codes (comma-separated); implies --error-handling
--return-null-for <codes>
Return the ErrNullResponse sentinel for these status codes; implies --error-handling
--return-error-for <codes>
Return a typed *HTTPStatusError for these status codes; implies --error-handling
--include-tags <tags>
Only generate operations carrying these tags (comma-separated)
--strict-validation
Fail on OpenAPI spec violations instead of tolerating them
--clean
Remove stale files from the output directory before writing
--verbose
Enable verbose logging
Options reference

Every knob, documented

Every option is available on the C# fluent API as a method, and most are also exposed as CLI flags. Cross-cutting auth, headers, retries and timeouts apply across frameworks.

Go Options

6
  • WithDocumentation()Generate Go doc comments on structs and service methods
  • WithOptionsObjectThreshold(int)Parameter count at which a method switches to an options struct
  • WithValidateStructTags()Emit validate:"…" struct tags (for github.com/go-playground/validator)
  • WithContext()Take context.Context as the first method parameter (engine default)
  • WithPointersForOmittable()Use pointers (*string, *int) for optional fields (engine default)
  • WithMethodNames(Func)Custom method naming rule

Auth · Headers · Resilience

14
  • WithErrorHandling()Smart error handling by HTTP-status semantics (404/403 → ErrNullResponse · 400/422/409 → error body · 401/500/502/503 → *HTTPStatusError)
  • WithErrorHandling(errors => errors...)Per-status routing: ReturnNullFor(404, 403) · ReturnErrorFor(400, 422) · ThrowFor(401, 500)
  • WithBearerAuth()Bearer token from env var (default API_TOKEN) — adds an Authorization header via middleware
  • WithBearerAuth(string)Bearer token from a specific env var name
  • WithBearerAuth(string, string)Bearer token from an env var with a custom header name
  • WithBasicAuth(string, string)HTTP Basic auth from username + password env vars
  • WithCustomHeader(string, string)Static header read from an env var. Repeatable.
  • WithBaseUrlEnvVar(string)Read the base URL from an env var (default API_BASE_URL)
  • WithTimeout(double)http.Client timeout in seconds for all operations
  • WithTimeout(double?, double?, double?, double?)Granular timeout: connect · read · write · pool
  • WithRetries()Retries with exponential backoff (default status 429, 503)
  • WithRetries(int)Retries with a custom max-attempts count
  • WithRetries(int, double, double, int[])Retries with full custom settings including status codes
  • WithMiddleware()Emit RoundTripper middleware infrastructure (chained request/response hooks)

OpenAPI Filtering

3
  • WithStrictValidation()Enable strict OpenAPI validation
  • WithOperationFilter(Func)Filter operations by predicate
  • WithHeaderFilter(Func)Filter header parameters

Naming Transformations

3
  • Types(Func)Transform type names
  • Paths(Func)Transform output paths
  • FileNames(Func)Transform file names

File Management

5
  • CleanDestination()Clean output directory before generation
  • AlwaysOverwrite()Always overwrite existing files
  • OnlyWhenModelChanged()Update only when model changes
  • OnlyWhenNew()Write only new files, preserve existing
  • CleanDirectories(...)Clean specific subdirectories

Diagnostics

2
  • Verbose()Enable verbose logging
  • WithLogger(Action<string>)Route generation log output to a custom sink
Features

Why this package is different

Deterministic output
Same spec + same options produce byte-identical files. Safe to commit, safe to diff in review, safe to cache in CI.
Flexible naming
Case conventions are configurable per role — types, properties, operations, enums. Idiomatic in the target by default.
Semver-honest
Spec diff drives the version bump. Additive changes = minor, removed operations = major. Never a surprise in your lockfile.