.Refitter File format

The following is an example .refitter file

• openApiPath - points to the OpenAPI Specifications file. This can be the path to a file stored on disk, relative to the .refitter file. This can also be a URL to a remote file that will be downloaded over HTTP/HTTPS
• namespace - the namespace used in the generated code. If not specified, this defaults to GeneratedCode
• naming.useOpenApiTitle - a boolean indicating whether the OpenApi title should be used. Default is true
• naming.interfaceName - the name of the generated interface. The generated code will automatically prefix this with I so if this set to MyApiClient then the generated interface is called IMyApiClient. Default is ApiClient
• generateContracts - a boolean indicating whether contracts should be generated. A use case for this is several API clients use the same contracts. Default is true
• generateXmlDocCodeComments - a boolean indicating whether XML doc comments should be generated. Default is true
• addAutoGeneratedHeader - a boolean indicating whether XML doc comments should be generated. Default is true
• addAcceptHeaders - a boolean indicating whether to add accept headers [Headers("Accept: application/json")]. Default is true
• returnIApiResponse - a boolean indicating whether to return IApiResponse<T> objects. Default is false
• responseTypeOverride - a dictionary with operation ids (as specified in the OpenAPI document) and a particular return type to use. The types are wrapped in a task, but otherwise unmodified (so make sure to specify or import their namespaces). Default is {}
• generateOperationHeaders - a boolean indicating whether to use operation headers in the generated methods. Default is true
• typeAccessibility - the generated type accessibility. Possible values are Public and Internal. Default is Public
• useCancellationTokens - Use cancellation tokens in the generated methods. Default is false
• useIsoDateFormat - Set to true to explicitly format date query string parameters in ISO 8601 standard date format using delimiters (for example: 2023-06-15). Default is false
• multipleInterfaces - Set to ByEndpoint to generate an interface for each endpoint, or ByTag to group Endpoints by their Tag (like SwaggerUI groups them).
• outputFolder - a string describing a relative path to a desired output folder. Default is ./Generated
• outputFilename - Output filename. Default is Output.cs when used from the CLI tool, otherwise its the .refitter filename. So Petstore.refitter becomes Petstore.cs.
• additionalNamespaces - A collection of additional namespaces to include in the generated file. A use case for this is when you want to reuse contracts from a different namespace than the generated code. Default is empty
• excludeNamespaces - A collection of regular expressions to exclude namespaces from the generated file. A use case for this is when your project has global usings where these namepsaces would be redundant. Default is empty
• includeTags - A collection of tags to use a filter for including endpoints that contain this tag.
• includePathMatches - A collection of regular expressions used to filter paths.
• generateDeprecatedOperations - a boolean indicating whether deprecated operations should be generated or skipped. Default is true
• operationNameTemplate - Generate operation names using pattern. This must contain the string {operationName}. An example usage of this could be {operationName}Async to suffix all method names with Async
• optionalParameters - Generate non-required parameters as nullable optional parameters
• trimUnusedSchema - Removes unreferenced components schema to keep the generated output to a minimum
• keepSchemaPatterns: A collection of regular expressions to force to keep matching schema. This is used together with trimUnusedSchema
• generateDefaultAdditionalProperties: Set to false to skip default additional properties. Default is true
• operationNameGenerator: The NSwag IOperationNameGenerator implementation to use. See https://refitter.github.io/api/Refitter.Core.OperationNameGeneratorTypes.html
• immutableRecords: Set to true to generate contracts as immutable records instead of classes. Default is false
• useDynamicQuerystringParameters: Set to true to wrap multiple query parameters into a single complex one. Default is false (no wrapping). See https://github.com/reactiveui/refit?tab=readme-ov-file#dynamic-querystring-parameters for more information.
• dependencyInjectionSettings - Setting this will generated extension methods to IServiceCollection for configuring Refit clients
  • baseUrl - Used as the HttpClient base address. Leave this blank to manually set the base URL
  • httpMessageHandlers - A collection of HttpMessageHandler that is added to the HttpClient pipeline
  • transientErrorHandler - This is the transient error handler to use. Possible values are None, Polly, and HttpResilience. Default is None
  • maxRetryCount - This is the max retry count used in the Polly retry policy. Default is 6
  • firstBackoffRetryInSeconds - This is the duration of the initial retry backoff. Default is 1 second
• apizrSettings - Setting this will format Refit interface to be managed by Apizr. See https://www.apizr.net for more information
  • withRequestOptions - Tells if the Refit interface methods should have a final IApizrRequestOptions options parameter
  • withRegistrationHelper - Tells if Refitter should generate Apizr registration helpers (extended with dependencyInjectionSettings set, otherwise static)
  • withCacheProvider - Set the cache provider to be used
  • withPriority - Tells if Apizr should handle request priority
  • withMediation - Tells if Apizr should handle request mediation (extended only)
  • withOptionalMediation - Tells if Apizr should handle optional request mediation (extended only)
  • withMappingProvider - Set the mapping provider to be used
  • withFileTransfer - Tells if Apizr should handle file transfer
• codeGeneratorSettings - Setting this allows customization of the NSwag generated types and contracts
  • requiredPropertiesMustBeDefined - Default is true,
  • generateDataAnnotations - Default is true,
  • anyType - Default is object,
  • dateType - Default is System.DateTimeOffset,
  • dateTimeType - Default is System.DateTimeOffset,
  • timeType - Default is System.TimeSpan,
  • timeSpanType - Default is System.TimeSpan,
  • arrayType - Default is System.Collections.Generic.ICollection,
  • dictionaryType - Default is System.Collections.Generic.IDictionary,
  • arrayInstanceType - Default is System.Collections.ObjectModel.Collection,
  • dictionaryInstanceType - Default is System.Collections.Generic.Dictionary,
  • arrayBaseType - Default is System.Collections.ObjectModel.Collection,
  • dictionaryBaseType - Default is System.Collections.Generic.Dictionary,
  • propertySetterAccessModifier - Default is ``,
  • generateImmutableArrayProperties - Default is false,
  • generateImmutableDictionaryProperties - Default is false,
  • handleReferences - Default is false,
  • jsonSerializerSettingsTransformationMethod - Default is null,
  • generateJsonMethods - Default is false,
  • enforceFlagEnums - Default is false,
  • inlineNamedDictionaries - Default is false,
  • inlineNamedTuples - Default is true,
  • inlineNamedArrays - Default is false,
  • generateOptionalPropertiesAsNullable - Default is false,
  • generateNullableReferenceTypes - Default is false,
  • - Default is false

To generate code from an OpenAPI specifications file, run the following:

This will generate a file called Output.cs which contains the Refit interface and contract classes generated using NSwag

Using the generated code

Here's an example generated output from the Swagger Petstore example using the default settings

Here's an example generated output from the Swagger Petstore example configured to generate an interface for each endpoint

CLI Tool

Output

Here's an example generated output from the Swagger Petstore example configured to generate an interface with dynamic querystring paremeters

CLI Tool

Output

RestService

Here's an example usage of the generated code above

The RestService class generates an implementation of ISwaggerPetstore that uses HttpClient to make its calls.

The code above when run will output something like this:

ASP.NET Core and HttpClientFactory

Here's an example Minimal API with the Refit.HttpClientFactory library:

.NET Core supports registering the generated ISwaggerPetstore interface via HttpClientFactory

The following request to the API above

Returns a response that looks something like this:

Dependency Injection

Refitter supports generating bootstrapping code that allows the user to conveniently configure all generated Refit interfaces by calling a single extension method to IServiceCollection.

This is enabled through the .refitter settings file like this:

which will generate an extension method to IServiceCollection called ConfigureRefitClients(). The generated extension method depends on Refit.HttpClientFactory library and looks like this:

This comes in handy especially when generating multiple interfaces, by tag or endpoint. For example, the following .refitter settings file

Will generate a single ConfigureRefitClients() extension methods that may contain dependency injection configuration code for multiple interfaces like this

Personally, they I use Refitter is to generate an interface per endpoint, so when generating code for a large and complex API, I might have several interfaces.

Apizr

Apizr is a Refit client manager that provides a set of features to enhance requesting experience with resilience, caching, priority, mediation, mapping, logging, authentication, file transfer capabilities and many more...

Generating the interfaces

Refitter supports generating Apizr formatted Refit interfaces that can be managed then by Apizr (v6+).

You can enable Apizr formatted Refit interface generation either:

• With the --use-apizr command line argument
• By setting the apizrSettings section in the .refitter settings file

Note that --use-apizr uses default Apizr settings with withRequestOptions set to true as recommended, while the .refitter settings file allows you to configure it deeper.

In both cases, it will format the generated Refit interfaces to be Apizr ready by:

• Adding a final IApizrRequestOptions options parameter to all generated methods (if withRequestOptions is set to true)
• Providing cancellation tokens by Apizr request options instead of a dedicated parameter (if withRequestOptions is set to true)
• Using method overloads instead of optional parameters (note that setting useDynamicQuerystringParameters to true improve overloading experience)

From here, you're definitly free to use the formatted interface with Apizr by registering, configuring and using it following the Apizr documentation. But Refitter can go further by generating some helpers to make the configuration easier.

Generating the helpers

Refitter supports generating Apizr (v6+) bootstrapping code that allows the user to conveniently configure all generated Apizr formatted Refit interfaces by calling a single method. It could be either an extension method to IServiceCollection if DependencyInjectionSettings are set, or a static builder method if not.

Extended

To enable Apizr registration code generation for IServiceCollection, you need at least to set the withRegistrationHelper property to true and configure the DependencyInjectionSettings section in the .refitter settings file. This is what the .refitter settings file may look like, depending on you configuration:

which will generate an extension method to IServiceCollection called ConfigurePetstoreApiApizrManager(). The generated extension method depends on Apizr.Extensions.Microsoft.DependencyInjection library and looks like this:

This comes in handy especially when generating multiple interfaces, by tag or endpoint. For example, the following .refitter settings file

Will generate a single ConfigurePetstoreApizrManagers() extension method that may contain dependency injection configuration code for multiple interfaces like this

Here, IPetApi, IStoreApi and IUserApi are the generated interfaces which share the same common configuration defined from the .refitter file.

Static

To enable Apizr static builder code generation, you need at least to set the withRegistrationHelper property to true and leave the DependencyInjectionSettings section to null in the .refitter settings file. This is what the .refitter settings file may look like, depending on you configuration:

which will generate a static builder method called BuildPetstore30ApizrManager(). The generated builder method depends on Apizr library and looks like this:

This comes in handy especially when generating multiple interfaces, by tag or endpoint. For example, the following .refitter settings file

Will generate a single BuildPetstoreApizrManagers() builder method that may contain configuration code for multiple interfaces like this

Here, IPetApi, IStoreApi and IUserApi are the generated interfaces which share the same common configuration defined from the .refitter file.

Customizing the configuration

You may want to adjust apis configuration, for example, to add a custom header to requests. This can be done using the Action<TApizrOptionsBuilder> parameter while calling the generated method. To know how to make Apizr fit your needs, please refer to the Apizr documentation.

Using the managers

Once you called the generated method, you will get an IApizrManager<T> instance that you can use to make requests to the API. Here's an example of how to use it:

Please head to the Apizr documentation to get more.

System requirements

.NET 8.0

For tips and tricks on software development, check out my blog

If you find this useful and feel a bit generous then feel free to buy me a coffee ☕