From a file
A file source is an OpenAPI document that lives with the code. It is the simplest source: the build needs no network once the packages are restored, and a change to the API shows up as a diff of the document.
Declare the client
Section titled “Declare the client”The Include is a path relative to the project. A .json file is read as JSON, and a .yaml or .yml file as YAML:
<ItemGroup> <OpenApiClient Include="openapi/rockets.yaml" Generator="Refitter" ClientName="RocketsClient" Namespace="MyApp.Rockets" /></ItemGroup>Anything that is not a project (.csproj, .fsproj, .vbproj) or a URL (http://, https://) is a file. A file that does not
exist fails the build with CHIRO102.
Configure the client
Section titled “Configure the client”The project writes no code for the client. Its registration, AddRocketsClient(), reads the client’s options from
Clients:RocketsClient or a connection string, takes a configure argument for code, and returns the IHttpClientBuilder for
handlers of your own:
builder.Services .AddRocketsClient(options => options.Timeout = TimeSpan.FromSeconds(30)) .AddStandardResilienceHandler();Authenticate the client
Section titled “Authenticate the client”Register the authentication keyed with the client’s name, then the client:
// Kiotabuilder.Services.AddKeyedSingleton<IAuthenticationProvider>( "RocketsClient", (services, _) => new BaseBearerTokenAuthenticationProvider(services.GetRequiredService<IAccessTokenProvider>()));
// Refitterbuilder.Services.AddKeyedSingleton( "RocketsClient", (services, _) => new RefitSettings { AuthorizationHeaderValueGetter = (request, cancellationToken) => services.GetRequiredService<ITokenSource>().GetTokenAsync(cancellationToken), });
builder.Services.AddRocketsClient();See Authentication for the lookup, and the options’ delegates that have the last word.
Several clients
Section titled “Several clients”Give each client its own ClientName, and its own Namespace when they share a project, so their generated types don’t collide:
<ItemGroup> <OpenApiClient Include="openapi/rockets.json" Generator="Kiota" ClientName="RocketsClient" Namespace="MyApp.Rockets" /> <OpenApiClient Include="openapi/launches.json" Generator="Refitter" ClientName="LaunchesClient" Namespace="MyApp.Launches" /></ItemGroup>Two clients can share a document, for example to compare the generators. Each one gets its own copy of the document in its own
folder in obj.
Updating the document
Section titled “Updating the document”Replace the file and build. Chirograph copies the document into obj only when its content changed, and the generator only runs
again when that copy, or the client’s settings, changed. Saving the file with the same content regenerates nothing. See
How generation runs.
Passing options to the generator
Section titled “Passing options to the generator”Options is added to the generator’s command line: after kiota generate … for Kiota, and after the settings file for Refitter.
<OpenApiClient Include="openapi/rockets.json" Generator="Kiota" ClientName="RocketsClient" Options="--include-path /rockets/**"/>A change to Options generates the client again. Options that change where the output goes or what the client is called fight with
the ones Chirograph passes; see Generators for what those are.