dotnet tool NuGet v1.0.0 MIT

MetaEngine.CSharp.OpenApi.HttpClient.Tool

OpenAPI 3.x → an idiomatic C# HttpClient API client and System.Text.Json models — the native .NET path. Smart HTTP-status error handling, bearer/basic auth, retries, custom headers, DataAnnotations validation and DI middleware. Ships as a NuGet library for programmatic/build-tool use plus a dotnet tool CLI.

OpenAPI 3.xMetaEngine IRC# · HttpClient
Try the interactive converter
Install

Pick your registry

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

dotnet toolPrimaryMetaEngine.CSharp.OpenApi.HttpClient.Tool
$dotnet tool install --global MetaEngine.CSharp.OpenApi.HttpClient.Tool
v1.0.0
NuGetMetaEngine.CSharp.OpenApi.HttpClient
$dotnet add package MetaEngine.CSharp.OpenApi.HttpClient
v1.0.0
Usage

Drive it from the CLI or programmatically

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

NuGet · dotnet tool · 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-csharp-httpclient <input> <output> <namespace> [options]

Installed as a global dotnet tool: dotnet tool install --global MetaEngine.CSharp.OpenApi.HttpClient.Tool. Takes three positional arguments in order — <input> (OpenAPI spec file path or URL), <output> (directory for the generated C# files), and <namespace> (root namespace for the client and models). Accepts OpenAPI 3.0 and 3.1 in JSON or YAML.

Quick examples
Install the tool
dotnet tool install --global MetaEngine.CSharp.OpenApi.HttpClient.Tool
Generate a client into MyApp.Api
metaengine-openapi-csharp-httpclient openapi.yaml ./Generated MyApp.Api
Bearer auth, retries, smart error handling and XML docs
metaengine-openapi-csharp-httpclient openapi.yaml ./Generated MyApp.Api \
  --bearer-auth API_TOKEN \
  --retries 3 \
  --error-handling \
  --documentation
Tag filtering, DI middleware and a tenant header from an env var
metaengine-openapi-csharp-httpclient https://api.example.com/openapi.json ./Generated MyApp.Api \
  --include-tags payments,refunds \
  --middleware \
  --custom-header X-Tenant-ID=TENANT_ID
CLI options
Option
Description
--include-tags <tags>
Only generate operations carrying these tags (comma-separated)
--service-suffix <suffix>
Rename generated *Service classes with this suffix (e.g. Client, Api)
--options-threshold <n>
Parameter count to use options object [default: 4]
--documentation
Generate XML doc comments from schema descriptions and examples
--validation-annotations
Emit System.ComponentModel.DataAnnotations attributes on models from spec constraints
--middleware
Generate middleware infrastructure (ApiDelegatingHandler + ServiceCollectionExtensions)
--error-handling
Enable smart error handling based on HTTP status semantics
--bearer-auth [ENV_VAR]
Bearer token from env var (default API_TOKEN). Adds an Authorization header to all requests.
--basic-auth
HTTP Basic auth from env vars (API_USERNAME / API_PASSWORD)
--retries [n]
Enable retries with exponential backoff. Optional value sets max attempts [default attempts: 3].
--custom-header <H=ENV>
Static header from env var. Repeatable. Format: <header-name>=<env-var-name> (e.g. X-Tenant-ID=TENANT_ID)
--strict-validation
Enable strict OpenAPI validation
--clean
Clean the destination directory before generating
--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.

HttpClient Options

5
  • WithMiddleware()Generate middleware infrastructure (ApiDelegatingHandler + ServiceCollectionExtensions AddApiClients) for DI registration. Required to route auth / header injection through a DelegatingHandler.
  • WithValidationAnnotations()Emit System.ComponentModel.DataAnnotations attributes ([Required], [StringLength], [Range], [EmailAddress], [RegularExpression]) on models from spec constraints (required, minLength/maxLength, minimum/maximum, format: email, pattern)
  • WithDocumentation()Emit XML doc comments (///) on methods and parameters from schema descriptions and examples
  • WithMethodNames(Func)Custom method naming rule with access to operation context
  • WithOptionsObjectThreshold(int)Parameter count at which a method collapses its parameters into an options object (default: 4)

Auth · Headers · Resilience

11
  • WithErrorHandling()Smart error handling on HttpClient based on HTTP status semantics (404 / 403 → null · 400 / 422 / 409 → error body · 401 / 500 / 502 / 503 → throw)
  • WithErrorHandling(errors => errors...)Per-status routing from a clean slate: ReturnNullFor(404, 403) · ReturnErrorFor(400, 422) · ThrowFor(401, 500)
  • WithBearerAuth()Bearer token from env var (default API_TOKEN) — adds an Authorization header to all requests
  • WithBearerAuth(string)Bearer token from a specific env var name
  • WithBearerAuth(string, string)Bearer token with custom header name (e.g. X-Api-Key)
  • WithBasicAuth()HTTP Basic auth from default env vars (API_USERNAME / API_PASSWORD) — Base64-encoded Authorization header
  • WithBasicAuth(string, string)HTTP Basic auth from custom username + password env vars
  • WithCustomHeader(string, string)Static header from env var. Repeatable (e.g. X-Tenant-ID ← TENANT_ID)
  • WithRetries()Retries with exponential backoff (default 3 attempts, base 0.5s / max 30s, status 429, 503)
  • WithRetries(int)Retries with a custom max-attempts count
  • WithRetries(int, double, double, int[])Retries with full custom settings: max attempts · base delay (s) · max delay (s) · trigger status codes

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.