Skip to content

OpenApiClient

An OpenApiClient item declares one client: a document, the generator that turns it into code, and the name of what is generated.

<ItemGroup>
<OpenApiClient Include="openapi/rockets.yaml" Generator="Refitter" ClientName="RocketsClient" Namespace="MyApp.Rockets" />
</ItemGroup>

Declare it in the project file, or in a Directory.Build.targets. The SDK reads the items when the project is evaluated (to add packages, tool downloads and server references) and again when it builds.

Metadata the item doesn’t read is ignored without a warning, so a misspelt name falls back to its default.

Metadata Required Default Meaning
Include yes The source. A .csproj, .fsproj or .vbproj is a server project. http:// or https:// is a URL. Anything else is a file (.json, .yaml, .yml), relative to the project.
Generator yes Kiota or Refitter (CHIRO100).
ClientName yes A C# identifier (CHIRO101), unique within the project (CHIRO108). Kiota’s client class is called this, Refitter’s interface is I<ClientName>, the registration is Add<ClientName>() and its configuration section is Clients:<ClientName>.
Namespace no $(RootNamespace) The namespace of everything generated for the client. Give each client its own when a project has several.
DocumentName no the only document Server project only: the document to generate from, when the server writes several. v1 is ASP.NET Core’s default (CHIRO103).
DocumentCache no the document’s copy in obj URL only: a file, relative to the project, to keep the last download in. Commit it to build without the URL. See Document cache.
UpdateDocumentCache no $(ChirographUpdateOpenApiDocumentCache), which is true URL only: false uses the cache whenever it exists instead of downloading. Wins over the property.
Options no More arguments for the generator: after kiota generate …, or after Refitter’s settings file. See Generators.
Authentication no A ;-separated list of the authentication methods the client may use beyond None, ApiKey, Bearer and Basic: ClientCredentials, which adds Duende.AccessTokenManagement and allows ClientCredentials and PrivateKeyJwt, and Azure, which adds Azure.Identity and allows AzureDefault, AzureManagedIdentity, AzureWorkloadIdentity and AzureServicePrincipal. An unknown value is CHIRO109. See Client credentials, Private key JWT and Azure.

DocumentName is ignored for a file or URL, and DocumentCache and UpdateDocumentCache for a file or server project.

  • Changing Generator, ClientName, Namespace or Options generates the client again on the next build. Changing Authentication only rewrites the registration and the options.
  • Changing Include to another document of the same content changes nothing: the client is generated from the content, not the path.
  • Removing an item leaves its folder in obj, but its code is no longer compiled.