apigenie-generator client csharp

Tier 1 · Release 0.12.0: Level 1 ✓ · Level 2 ✓ · Level 3 ✓ · Verification

Generate a C# client of an OpenAPI document, built on HttpClient and System.Text.Json, for .NET 8 (or 9 and 10).

From an AsyncAPI document, the command generates a C# Kafka client library instead; see apigenie-generator client csharp (AsyncAPI).

Usage

apigenie-generator client csharp [...OPTIONS] INPUT_FILE

Description

The input must be an OpenAPI 3.0, 3.1 or 3.2 document or, since 0.12.0, a Swagger 2.0 document (see Swagger 2.0 input). The output is a class library: a .csproj targeting net8.0 with nullable reference types, which references only Microsoft.Extensions.Http (for the registration with dependency injection).

services.AddPetStoreClient(options =>
{
    options.BaseUrl = new Uri("https://api.example.com/v1");
    options.ApiKey = ApiCredential.Static(configuration["PetStore:ApiKey"]!);
});

// inject PetStoreClient, or the client of a group, e.g. IPetsClient
var pets = await client.Pets.ListPetsAsync(limit: 10, cancellationToken: token);
try
{
    var pet = await client.Pets.GetPetAsync(42);
}
catch (ApiException error) when (error.StatusCode == 404)
{
    Console.WriteLine(error.Problem?.Detail);
}

Without dependency injection, PetStoreClient.CreateHttpClient(options) makes an HttpClient that sends the credentials: new PetStoreClient(PetStoreClient.CreateHttpClient(options), options).

The generated code has:

  • Clients. One interface and one client per group of operations (IPetsClient, PetsClient), grouped by their first tag (see grouping), and PetStoreClient with a property per group. The clients take the HttpClient in their constructor, so IHttpClientFactory manages them; AddPetStoreClient() registers them as typed clients, with the options and the handlers sending the credentials. Operations marked x-internal are left out.

  • Methods. An async method per operation, named after its operation ID (ListPetsAsync, see action_naming): path parameters, the other required parameters and the body first, optional parameters (null leaves them out) and a CancellationToken last. Parameters are sent in their style (form, spaceDelimited, pipeDelimited, deepObject, simple, label, matrix), objects included; parameters described by content are sent as JSON. Deprecated operations are [Obsolete].

  • Bodies. JSON (with the media type of the document, e.g. application/merge-patch+json), text, binary (Stream), JSON Lines uploads (IAsyncEnumerable<T>), and forms and multipart bodies as *Form classes, whose files are FileParts (format: binary or contentMediaType) sent with the content type of their encoding.

  • Responses. The method returns the body of the success response (Task<Pet>), nothing (Task), or, when statuses have different bodies, a *Result with the status, the headers and a property per status. Responses with a status of 400 or more throw an ApiException with the status, the headers, the body as text and its RFC 9457 problem details (Problem). text/event-stream responses are IAsyncEnumerable<ServerSentEvent<T>>, typed by the contentSchema of the events’ data (OpenAPI 3.2 itemSchema, or x-itemSchema), JSON Lines responses IAsyncEnumerable<T>, both read as they arrive; binary responses are BinaryResponses to dispose. Each other media type of a body or a response is a method of its own, named after it: UpdatePetJsonPatchAsync, GetLabelPdfAsync, GetEventsEventStreamAsync.

  • Servers. Requests go to BaseUrl, else to the base address of the HttpClient, else to the first server of the operation, of its path or of the API, with ServerVariables for their variables.

  • Security. A credential per security scheme in the options (ApiCredential.Static, ApiCredential.FromProvider for tokens that change, ApiCredential.Basic). A request carries the credentials of the first alternative of its operation’s security requirements whose credentials are set; the AuthorizationHandler (HTTP schemes such as bearer and basic, OAuth 2.0, OpenID Connect) and ApiKeyHandler (headers, query parameters, cookies) delegating handlers add them.

  • OAuth 2.0 (since 0.12.0). When a scheme has client credentials, authorization code or device authorization flows, Infrastructure/OAuth.cs has an OAuthClient. Create it with the flows of the scheme (SecurityScheme.Flows, in PetStoreSecuritySchemes.All), the client ID and, for a confidential client, the secret. ClientCredentials() returns an ApiCredential. The authorization code flow with PKCE (CreateAuthorizationRequest(), then ExchangeCodeAsync()) and the device authorization flow of OpenAPI 3.2 (StartDeviceAuthorizationAsync(), then PollDeviceAuthorizationAsync()) return OAuthTokens, which FromTokens(tokens, flow) makes an ApiCredential, with the flow that issued them, e.g. scheme.Flows!.AuthorizationCode. Credentials renew their access token 30 seconds before it expires, with the refresh token when there is one. Without one, or when the server refuses it, ClientCredentials() credentials ask for new tokens, and FromTokens() credentials keep the access token until the server refuses it. Errors of the authorization server, a refused refresh token among them, throw an OAuthException. The password and implicit flows are left to tokens from elsewhere.

    var scheme = PetStoreSecuritySchemes.All.First(s => s.Name == "oauth2");
    var oauth = new OAuthClient(scheme.Flows!, "my-client-id", "my-secret");
    services.AddPetStoreClient(options => options.Oauth2 = oauth.ClientCredentials());
  • Models. Records and enums, as apigenie-generator server aspnet writes them: required/init properties, DataAnnotations for constraints (exclusive bounds of OpenAPI 3.0 and 3.1 alike), nullable types for nullable, null types and oneOf with null. allOf is merged into one record, or is inheritance ([JsonPolymorphic]/[JsonDerivedType]) when the base has a discriminator. oneOf and anyOf with a discriminator are abstract records whose variants are told apart by the discriminator value (explicit mapping, or the const of the discriminator property, or the schema name), read and written by generated converters wherever the discriminator is in the object; values with an unknown discriminator are read as the default mapping (defaultMapping, or x-defaultMapping). Unions whose members have one C# type (e.g. strings of different formats) have that type.

  • Tuples, patterns and conditions (since 0.12.0). Tuples (prefixItems) are lists of the type their positions share, or of object when they differ, with a MaxLength when items: false closes them. A patternProperties schema without properties is a dictionary of the type of its one pattern. With several patterns, it is a record whose Entries hold the values as JsonElements. multipleOf is a [MultipleOf] attribute. Some records implement IValidatableObject and check in Validate():

    • records with if/then/else, dependentRequired or dependentSchemas conditions on which properties are present and their constant values;
    • records with additionalProperties: false, for keys that match no pattern.

    The server’s endpoint filter checks these attributes and Validate(); the client doesn’t call them.

  • JSON. A System.Text.Json source-generated JsonSerializerContext (PetStoreJsonContext) with every model and body type, so the clients read and write JSON without reflection. Use it to read error bodies: JsonSerializer.Deserialize(error.Content!, PetStoreJsonContext.Default.Error).

The project also has README.md, Infrastructure/ (the runtime of the clients) and Serialization/ (the JSON context and converters). The code builds with -warnaserror and the .NET analyzers.

Not supported:

  • receiving callbacks and webhooks (the client has no server for them);
  • mutual TLS (configure the client certificate on the HTTP handler);
  • XML bodies (sent and read as text);
  • the type of each position of a tuple;
  • patternProperties beside properties, the keys of a one-pattern dictionary and the values of Entries (not checked);
  • conditions on anything other than the presence and constant values of properties, and unevaluatedProperties;
  • retries (add a resilience handler with configureHttpClient) and pagination.

Extensions

Extension Effect
x-apigenie.codegen.controller-name on an operation or its path item: the group (client) of the operation, whatever grouping says
x-apigenie.codegen.action-name name of the method of an operation, when action_naming lists extension
x-apigenie.codegen.disabled true on an operation or its path item leaves the operation out, unless skip_disabled is false
x-internal true on an operation leaves it out
x-enum-varnames, x-enum-names names of the members of an enum, in PascalCase
x-enum-descriptions, x-enumDescriptions documentation comments of the members of an enum
x-defaultMapping defaultMapping of a discriminator in OpenAPI 3.0 and 3.1 documents: the schema of the values whose discriminator value isn’t mapped
x-itemSchema itemSchema of a media type in OpenAPI 3.0 and 3.1 documents: the type of the items of a streamed response

The extensions can live in an overlay for this target instead of in the document, e.g. csharp.overlay.yaml:

overlay: 1.0.0
info:
  title: C# names
  version: 1.0.0
actions:
  - target: $.components.schemas.PetStatus
    update:
      x-enum-varnames: [Available, OnHold, Sold]
  - target: $.paths['/pets']
    update:
      x-apigenie:
        codegen:
          controller-name: Animals
apigenie-generator client csharp openapi.yaml --overlay csharp.overlay.yaml -o out

Options

-c, –config

Path to the configuration file to use. See the “Configuration” section for more information.

–overlay OVERLAY

Path to an OpenAPI Overlay (1.0 to 1.2) applied to the input before generating, e.g. one setting the extensions of the “Extensions” section. Can be repeated: the overlays apply in order, after those listed under commands.generate.client_csharp.overlay in the configuration file (with paths relative to it). Warnings and errors about a value an overlay set point to the overlay.

–strict

Makes an overlay action whose target selects nothing an error (exit status 2, nothing is generated) instead of a warning (OVERLAY:LINE:COL: action #N (TARGET) selects no nodes.).

–check

Writes nothing: compares what the generator would write with the output directory, prints the files that would be created or changed, and exits with 1 when there are any (since 0.12.0). See Check that generated code is up to date.

-o, –output

Directory where the project is generated.

–package-name

Root namespace of the generated code, e.g. Acme.PetStore.Client; also the name of the project. The API-wide types are named after its last segment (or the one before when it is Client, Clients or Sdk): PetStoreClient, PetStoreClientOptions. Defaults to the title of the API followed by .Client.

–package-version

Version of the project. Defaults to the version of the API when it’s a valid .NET version, or 1.0.0.

-p, –property NAME=VALUE

Sets an option (see below), e.g. -p layout=sources; can be repeated. Options given on the command line take precedence over the configuration file. OpenAPI documents only: using it with an AsyncAPI document is an error.

Configuration

The options are read from commands.generate.client_csharp. Its asyncapi section configures the generation from AsyncAPI documents (see apigenie-generator client csharp (AsyncAPI)).

version: '1.0'
commands:
  generate:
    client_csharp:
      namespace: Acme.PetStore.Client
      target_framework: net9.0
      grouping: tag
      dependency_injection: true
Option Values Description
layout project, sources project (default): a class library (.csproj, README.md and the sources); sources: only the generated sources, for an existing project
namespace namespace Root namespace of the generated code (also --package-name); derived from the API title by default, e.g. PetStore.Client
target_framework net8.0, net9.0, net10.0 Target framework of the project (default: net8.0)
grouping tag, url Grouping of operations into clients: by their first tag (default), or by the first segment of their paths
action_naming id, extension, url Sources of method names, in order of preference (default: id, url)
dependency_injection true, false Generate the registration of the clients with IServiceCollection and IHttpClientFactory (default: true; it references Microsoft.Extensions.Http)
skip_deprecated true, false Don’t generate deprecated operations (default: false)
skip_disabled true, false Don’t generate operations disabled with the x-apigenie extension (default: true)
model_suffix text Suffix of model names, e.g. Dto
version version Version of the project (also --package-version); defaults to the version of the API

Unknown options are errors.

Verification

The codegen conformance suite runs this target on the Carpet Express OpenAPI fixture. Level 1 compares the output with its snapshots and checks each feature, Level 2 runs the language's type checker and linter, and Level 3 runs the generated code in contract tests against the fixture. All targets.

This target's support tier is Tier 1. It goes through all three levels before every release, with the goal of supporting every feature of the fixture. Its unsupported features are worked on first.

ResultsLevel 1Level 2Level 3
Release 0.12.0✓ snapshots of 3.2, 3.1, 3.0, 2.0; 3.2: 37 supported, 0 not yet✓ pass (.NET SDK 8.0.204)✓ 37 of 37 operations pass (dotnet)
Development version✓ snapshots of 3.2, 3.1, 3.0, 2.0; 3.2: 37 supported, 0 not yetruns before a releaseruns before a release
Was this helpful?