https://github.com/christianhelle/refitter
A tool for generating Refit interfaces and contracts from OpenAPI specifications
https://github.com/christianhelle/refitter
csharp-sourcegenerator openapi openapi3 refit rest swagger
Last synced: 18 days ago
JSON representation
A tool for generating Refit interfaces and contracts from OpenAPI specifications
- Host: GitHub
- URL: https://github.com/christianhelle/refitter
- Owner: christianhelle
- License: mit
- Created: 2023-02-07T23:18:12.000Z (about 3 years ago)
- Default Branch: main
- Last Pushed: 2025-05-12T19:50:16.000Z (9 months ago)
- Last Synced: 2025-05-12T20:51:11.546Z (9 months ago)
- Topics: csharp-sourcegenerator, openapi, openapi3, refit, rest, swagger
- Language: C#
- Homepage: https://refitter.github.io
- Size: 3.9 MB
- Stars: 285
- Watchers: 5
- Forks: 53
- Open Issues: 28
-
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
- Funding: .github/FUNDING.yml
- License: LICENSE
Awesome Lists containing this project
README
[](https://github.com/christianhelle/refitter/actions/workflows/build.yml)
[](https://github.com/christianhelle/refitter/actions/workflows/smoke-tests.yml)
[](https://www.nuget.org/packages/refitter)
[](https://sonarcloud.io/summary/new_code?id=christianhelle_refitter)
[](https://codecov.io/gh/christianhelle/refitter)
[](#contributors-)
# Refitter
Refitter is a tool for generating a C# REST API Client using the [Refit](https://github.com/reactiveui/refit) library. Refitter can generate the Refit interface and contracts from OpenAPI specifications. Refitter could format the generated Refit interface to be managed by [Apizr](https://www.apizr.net) (v6+) and generate some registration helpers too.
Refitter comes in 3 forms:
- A [.NET CLI Tool](#cli-tool) distributed via [nuget.org](http://www.nuget.org/packages/refitter) that outputs a single C# file on disk
- An [MSBuild Task](#msbuild) via the [Refitter.MSBuild](http://www.nuget.org/packages/refitter.msbuild) package that integrates seamlessly into your build pipeline and automatically generates code at build time based on [.refitter](#.refitter-file-format) files within the project directory
- A [C# Source Generator](#source-generator) via the [Refitter.SourceGenerator](http://www.nuget.org/packages/refitter.sourcegenerator) package that generates code on compile time based on a [.refitter](#.refitter-file-format) within the project directory
## CLI Tool
### Installation
The tool is packaged as a .NET Tool and is published to nuget.org. You can install the latest version of this tool like this:
```shell
dotnet tool install --global Refitter
```
### Usage
```shell
refitter --help
```
```text
USAGE:
refitter [URL or input file] [OPTIONS]
EXAMPLES:
refitter ./openapi.json
refitter https://petstore3.swagger.io/api/v3/openapi.yaml
refitter ./openapi.json --settings-file ./openapi.refitter --output ./GeneratedCode.cs
refitter ./openapi.json --namespace "Your.Namespace.Of.Choice.GeneratedCode" --output ./GeneratedCode.cs
refitter ./openapi.json --namespace "Your.Namespace.Of.Choice.GeneratedCode" --internal
refitter ./openapi.json --output ./IGeneratedCode.cs --interface-only
refitter ./openapi.json --output ./GeneratedContracts.cs --contract-only
refitter ./openapi.json --use-api-response
refitter ./openapi.json --cancellation-tokens
refitter ./openapi.json --no-operation-headers
refitter ./openapi.json --ignored-operation-headers "header-one" --ignored-operation-headers "Header-Two"
refitter ./openapi.json --no-accept-headers
refitter ./openapi.json --use-iso-date-format
refitter ./openapi.json --additional-namespace "Your.Additional.Namespace" --additional-namespace "Your.Other.Additional.Namespace"
refitter ./openapi.json --multiple-interfaces ByEndpoint
refitter ./openapi.json --tag Pet --tag Store --tag User
refitter ./openapi.json --match-path '^/pet/.*'
refitter ./openapi.json --trim-unused-schema
refitter ./openapi.json --trim-unused-schema --keep-schema '^Model$' --keep-schema '^Person.+'
refitter ./openapi.json --no-deprecated-operations
refitter ./openapi.json --operation-name-template '{operationName}Async'
refitter ./openapi.json --optional-nullable-parameters
refitter ./openapi.json --use-polymorphic-serialization
refitter ./openapi.json --collection-format Csv
refitter ./openapi.json --simple-output
refitter ./openapi.json --no-inline-json-converters
ARGUMENTS:
[URL or input file] URL or file path to OpenAPI Specification file
OPTIONS:
DEFAULT
-h, --help Prints help information
-v, --version Prints version information
-s, --settings-file Path to .refitter settings file. Specifying this will ignore all other settings (except for --output)
-n, --namespace GeneratedCode Default namespace to use for generated types
--contracts-namespace Default namespace to use for generated contracts
-o, --output Output.cs Path to Output file or folder (if multiple files are generated)
--contracts-output Output path for generated contracts. Enabling this automatically enables generating multiple files
--no-auto-generated-header Don't add header to output file
--no-accept-headers Don't add header to output file
--interface-only Don't generate contract types
--contract-only Don't generate clients
--use-api-response Return Task> instead of Task
--use-observable-response Return IObservable instead of Task
--internal Set the accessibility of the generated types to 'internal'
--cancellation-tokens Use cancellation tokens
--no-operation-headers Don't generate operation headers
--no-logging Don't log errors or collect telemetry
--additional-namespace Add additional namespace to generated types
--exclude-namespace Exclude namespace on generated types
--use-iso-date-format Explicitly format date query string parameters in ISO 8601 standard date format using delimiters (2023-06-15)
--multiple-interfaces Generate a Refit interface for each endpoint. May be one of ByEndpoint, ByTag
--multiple-files Generate multiple files instead of a single large file.
The output files can be the following:
- RefitInterfaces.cs
- DependencyInjection.cs
- Contracts.cs
--match-path Only include Paths that match the provided regular expression. May be set multiple times
--tag Only include Endpoints that contain this tag. May be set multiple times and result in OR'ed evaluation
--skip-validation Skip validation of the OpenAPI specification
--no-deprecated-operations Don't generate deprecated operations
--operation-name-template Generate operation names using pattern. When using --multiple-interfaces ByEndpoint, this is name of the Execute() method in the interface where all instances of the string '{operationName}' is replaced with 'Execute'
--optional-nullable-parameters Generate nullable parameters as optional parameters
--trim-unused-schema Removes unreferenced components schema to keep the generated output to a minimum
--keep-schema Force to keep matching schema, uses regular expressions. Use together with "--trim-unused-schema". Can be set multiple times
--include-inheritance-hierarchy Keep all possible inherited types/union types even if they are not directly used
--no-banner Don't show donation banner
--simple-output Generate simple, plain-text console output without ASCII art, tables, emojis, or color formatting (suitable for IDE output windows)
--skip-default-additional-properties Set to true to skip default additional properties
--collection-format Multi Determines the format of collection parameters. May be one of Multi, Csv, Ssv, Tsv, Pipes
--operation-name-generator Default The NSwag IOperationNameGenerator implementation to use.
May be one of:
- Default
- MultipleClientsFromOperationId
- MultipleClientsFromPathSegments
- MultipleClientsFromFirstTagAndOperationId
- MultipleClientsFromFirstTagAndOperationName
- MultipleClientsFromFirstTagAndPathSegments
- SingleClientFromOperationId
- SingleClientFromPathSegments
See https://refitter.github.io/api/Refitter.Core.OperationNameGeneratorTypes.html for more information
--immutable-records Generate contracts as immutable records instead of classes
--use-apizr Use Apizr by:
- Adding a final IApizrRequestOptions options parameter to all generated methods
- Providing cancellation tokens by Apizr request options instead of a dedicated parameter
- Using method overloads instead of optional parameters
See https://refitter.github.io for more information and https://www.apizr.net to get started with Apizr
--use-dynamic-querystring-parameters Enable wrapping multiple query parameters into a single complex one. Default is no wrapping.
See https://github.com/reactiveui/refit?tab=readme-ov-file#dynamic-querystring-parameters for more information
--use-polymorphic-serialization Use System.Text.Json polymorphic serialization.
Replaces NSwag JsonInheritanceConverter attributes with System.Text.Json JsonPolymorphicAttributes.
To have the native support of inheritance (de)serialization and fallback to base types when
payloads with (yet) unknown types are offered by newer versions of an API
See https://learn.microsoft.com/en-us/dotnet/standard/serialization/system-text-json/polymorphism for more information
--disposable Generate refit clients that implement IDisposable
--no-inline-json-converters Don't inline JsonConverter attributes for enum properties. When disabled, enum properties will not have [JsonConverter(typeof(JsonStringEnumConverter))] attributes
--integer-type int The .NET type to use for OpenAPI integer types without a format specifier. Common values: 'int' (default), 'long'
--custom-template-directory Custom directory with NSwag fluid templates for code generation. Default is null which uses the default NSwag templates. See
```
To generate code from an OpenAPI specifications file, run the following:
```shell
refitter [path to OpenAPI spec file] --namespace "[Your.Namespace.Of.Choice.GeneratedCode]"
```
This will generate a file called `Output.cs` which contains the Refit interface and contract classes generated using [NSwag](https://github.com/RicoSuter/NSwag)
### CLI Tool Output Example
Here's what the console output looks like when running the Refitter CLI tool:
### Simple Output Mode
For integration with IDEs and build tools that don't support rich console formatting, Refitter provides a `--simple-output` option:
```shell
refitter ./openapi.json --simple-output
```
This mode generates plain text output without:
- ASCII art and banners
- Colored text and rich formatting
- Unicode characters and emojis
- Tables and panels
This is particularly useful when:
- Running Refitter from Visual Studio extensions
- Integrating with build systems that capture console output
- Using tools that don't support ANSI escape sequences
- Running in environments with limited console capabilities
## .Refitter File format
The following is an example `.refitter` file
```js
{
"openApiPath": "/path/to/your/openAPI", // Required
"namespace": "Org.System.Service.Api.GeneratedCode", // Optional. Default=GeneratedCode
"contractsNamespace": "Org.System.Service.Api.GeneratedCode.Contracts", // Optional. Default=GeneratedCode
"naming": {
"useOpenApiTitle": false, // Optional. Default=true
"interfaceName": "MyApiClient" // Optional. Default=ApiClient
},
"generateContracts": true, // Optional. Default=true
"generateClients": true, // Optional. Default=true
"generateXmlDocCodeComments": true, // Optional. Default=true
"generateStatusCodeComments": true, // Optional. Default=true
"addAutoGeneratedHeader": true, // Optional. Default=true
"addAcceptHeaders": true, // Optional. Default=true
"addContentTypeHeaders": true, // Optional. Default=true
"returnIApiResponse": false, // Optional. Default=false
"responseTypeOverride": { // Optional. Default={}
"File_Upload": "IApiResponse",
"File_Download": "System.Net.Http.HttpContent"
},
"generateOperationHeaders": true, // Optional. Default=true
"ignoredOperationHeaders": ["apiKey"], // Optional. Default=[]
"typeAccessibility": "Public", // Optional. Values=Public|Internal. Default=Public
"useCancellationTokens": false, // Optional. Default=false
"useIsoDateFormat": false, // Optional. Default=false
"multipleInterfaces": "ByEndpoint", // Optional. May be one of "ByEndpoint" or "ByTag"
"generateDeprecatedOperations": false, // Optional. Default=true
"operationNameTemplate": "{operationName}Async", // Optional. Must contain {operationName}. When multipleInterfaces == "ByEndpoint", this is name of the Execute() method in the interface where all instances of the string '{operationName}' is replaced with 'Execute'
"optionalParameters": false, // Optional. Default=false
"outputFolder": "../CustomOutput" // Optional. Default=./Generated
"outputFilename": "RefitInterface.cs", // Optional. Default=Output.cs for CLI tool
"contractsOutputFolder": "../Contracts", // Optional. Default=NULL
"generateMultipleFiles": false, // Optional. Default=false
"additionalNamespaces": [ // Optional
"Namespace1",
"Namespace2"
],
"includeTags": [ // Optional. OpenAPI Tag to include when generating code
"Pet",
"Store",
"User"
],
"includePathMatches": [ // Optional. Only include Paths that match the provided regular expression
"^/pet/.*",
"^/store/.*"
],
"trimUnusedSchema": false, // Optional. Default=false
"keepSchemaPatterns": [ // Optional. Force to keep matching schema, uses regular expressions. Use together with trimUnusedSchema=true
"^Model$",
"^Person.+"
],
"includeInheritanceHierarchy": false, // Optional. Default=false. Set to true to keep all possible type-instances of inheritance/union types. This works in conjunction with trimUnusedSchema.
"generateDefaultAdditionalProperties": true, // Optional. default=true
"operationNameGenerator": "Default", // Optional. May be one of Default, MultipleClientsFromOperationId, MultipleClientsFromPathSegments, MultipleClientsFromFirstTagAndOperationId, MultipleClientsFromFirstTagAndOperationName, MultipleClientsFromFirstTagAndPathSegments, SingleClientFromOperationId, SingleClientFromPathSegments
"immutableRecords": false,
"useDynamicQuerystringParameters": true, // Optional. Default=false
"usePolymorphicSerialization": true, // Optional. Default=false
"generateDisposableClients": true, // Optional. Default=false
"dependencyInjectionSettings": { // Optional
"baseUrl": "https://petstore3.swagger.io/api/v3", // Optional. Leave this blank to set the base address manually
"httpMessageHandlers": [ // Optional
"AuthorizationMessageHandler",
"TelemetryMessageHandler"
],
"usePolly": true, // DEPRECATED - Use "transientErrorHandler": "None|Polly|HttpResilience" instead
"transientErrorHandler": "HttpResilience", // Optional. Set this to configure transient error handling with a retry policy that uses a jittered backoff. May be one of None, Polly, HttpResilience
"maxRetryCount": 3, // Optional. Default=6
"firstBackoffRetryInSeconds": 0.5 // Optional. Default=1.0
},
"apizrSettings": { // Optional
"withRequestOptions": true, // Optional. Default=true
"withRegistrationHelper": true, // Optional. Default=false
"withCacheProvider": "InMemory", // Optional. Values=None|Akavache|MonkeyCache|InMemory|DistributedAsString|DistributedAsByteArray. Default=None
"withPriority": true, // Optional. Default=false
"withMediation": true, // Optional. Default=false
"withOptionalMediation": true, // Optional. Default=false
"withMappingProvider": "AutoMapper", // Optional. Values=None|AutoMapper|Mapster. Default=None
"withFileTransfer": true // Optional. Default=false
},
"codeGeneratorSettings": { // Optional. Default settings are the values set in this example
"requiredPropertiesMustBeDefined": true,
"generateDataAnnotations": true,
"anyType": "object",
"dateType": "System.DateTimeOffset",
"dateTimeType": "System.DateTimeOffset",
"timeType": "System.TimeSpan",
"timeSpanType": "System.TimeSpan",
"arrayType": "System.Collections.Generic.ICollection",
"dictionaryType": "System.Collections.Generic.IDictionary",
"arrayInstanceType": "System.Collections.ObjectModel.Collection",
"dictionaryInstanceType": "System.Collections.Generic.Dictionary",
"arrayBaseType": "System.Collections.ObjectModel.Collection",
"dictionaryBaseType": "System.Collections.Generic.Dictionary",
"integerType": "Int32", // Optional. Default="Int32". The .NET type for OpenAPI integers without a format. Possible values: "Int32", "Int64"
"propertySetterAccessModifier": "",
"generateImmutableArrayProperties": false,
"generateImmutableDictionaryProperties": false,
"handleReferences": false,
"jsonSerializerSettingsTransformationMethod": null,
"generateJsonMethods": false,
"enforceFlagEnums": false,
"inlineNamedDictionaries": false,
"inlineNamedTuples": true,
"inlineNamedArrays": false,
"generateOptionalPropertiesAsNullable": false,
"generateNullableReferenceTypes": false,
"generateNativeRecords": false,
"generateDefaultValues": true,
"inlineNamedAny": false,
"inlineJsonConverters": true, // Optional. Default=true. Set to false to not generate JsonConverter attributes for enum properties
"dateFormat": "yyyy-MM-dd",
"dateTimeFormat": "yyyy-MM-dd",
"excludedTypeNames": [
"ExcludedTypeFoo",
"ExcludedTypeBar"
],
"customTemplateDirectory": "./path/to/directory/" // Optional. See
}
}
```
- `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`
- `generateClients`: - a boolean indicating whether clients should be generated. A use case for this is to seperate clients and contracts in two generation
- `generateXmlDocCodeComments` - a boolean indicating whether XML doc comments should be generated. Default is `true`
- `generateStatusCodeComments` - a boolean indicating whether the XML docs for `ApiException` and `IApiResponse` contain detailed descriptions for every documented status code. 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` 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`
- `ignoredOperationHeaders` - A collection of headers to omit from operation signatures. Default is `[]`
- `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
- `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. When using multiple interfaces with `ByEndpoint`, this is name of the Execute() method in the interface where all instances of the string '{operationName}' is replaced with 'Execute'
- `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`
- `includeInheritanceHierarchy`: Set to true to keep all possible type-instances of inheritance/union types. If this is false only directly referenced types will be kept. This works in conjunction with `trimUnusedSchema`
- `generateDefaultAdditionalProperties`: Set to `false` to skip default additional properties. Default is `true`
- `operationNameGenerator`: The NSwag `IOperationNameGenerator` implementation to use. See
- `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 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
- `usePolly` - Set this to `true` to configure the HttpClient to use Polly using a retry policy with a jittered backoff. This is **DEPRECATED**, use `transientErrorHandler` instead
- `transientErrorHandler`: Set this to configure transient error handling with a retry policy that uses a jittered backoff. See
- `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 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`,
- `integerType` - Default is `Int32`. The .NET type to use for OpenAPI integer types without a format specifier. Possible values: `Int32`, `Int64`
- `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,
- `generateNativeRecords` - Default is false
- `generateDefaultValues` - Default is true
- `inlineNamedAny` - Default is false
- `inlineJsonConverters` - Default is true. When set to false, enum properties will not have `[JsonConverter(typeof(JsonStringEnumConverter))]` attributes
- `dateFormat` - Default is null
- `dateTimeFormat` - Default is null
- `excludedTypeNames` - Default is empty
## MSBuild
This is the recommended approach for generating code from OpenAPI specifications at build time. The MSBuild approach integrates seamlessly into your build pipeline, automatically generates code at build time
### Why Choose MSBuild over Source Generator?
The MSBuild task offers several advantages over the Source Generator:
- **Build-time Generation**: Code is generated during the pre-build process, which ensures that the Refit source generator will work without needing to rebuild a second time.
- **No Manual Commits**: Generated files are created automatically during build, eliminating the need to commit generated code to source control
- **No Additional Tools Required**: Works out of the box without requiring separate CLI tool installation
### Installation
The MSBuild task is distributed as a NuGet package:
```shell
dotnet add package Refitter.MSBuild
```
### Usage
Once installed, the MSBuild task will automatically scan your project for `.refitter` files and generate code during build. Simply create a `.refitter` file in your project directory with your OpenAPI specification settings.
The MSBuild package includes a custom `.target` file which executes the `RefitterGenerateTask` custom task:
```xml
```
The `RefitterGenerateTask` task will scan the project folder for `.refitter` files and execute them all.
### Configuration
By default, telemetry collection is enabled. To opt-out, add the following to your `.csproj` file:
```xml
true
```
You can also skip OpenAPI validation by setting:
```xml
true
```
### Example
Create a `.refitter` file in your project:
```json
{
"openApiPath": "https://petstore3.swagger.io/api/v3/openapi.json",
"namespace": "Petstore.Api",
"outputFolder": "./Generated"
}
```
Now, every time you build your project, Refitter will automatically generate the API client code based on your OpenAPI specification.
### Alternative: Using CLI with MSBuild Exec Task
If you prefer more control or need to use the CLI tool directly, you can invoke the Refitter CLI from MSBuild pre-build events:
```xml
```
This approach requires that Refitter is installed as a local tool using a manifest file, as described in [this tutorial](https://learn.microsoft.com/en-us/dotnet/core/tools/local-tools-how-to-use?WT.mc_id=DT-MVP-5004822).
## Source Generator
> **Note:** We recommend using the [MSBuild](#msbuild) approach instead of the Source Generator because the code is generated at pre-compile, ensuring that the Refit source generator will generated code from the Refit interfaces added to the compilation
Refitter is available as a C# Source Generator that uses the [Refitter.Core](https://github.com/christianhelle/refitter/tree/main/src/Refitter.Core) library for generating a REST API Client using the [Refit](https://github.com/reactiveui/refit) library. Refitter can generate the Refit interface from OpenAPI specifications. Refitter could format the generated Refit interface to be managed by [Apizr](https://www.apizr.net) and generate some registration helpers too.
The Refitter source generator is a bit untraditional in a sense that it creates a folder called `Generated` in the same location as the `.refitter` file and generates files to disk under the `Generated` folder (can be changed with `--outputFolder`). The source generator output should be included in the project and committed to source control. This is done because there is no other way to trigger the Refit source generator to pickup the Refitter generated code
***(Translation: I couldn't for the life of me figure how to get that to work, sorry)***
### Installation
The source generator is distributed as a NuGet package and should be installed to the project that will contain the generated code
```shell
dotnet add package Refitter.SourceGenerator
```
### Usage
This source generator generates code based on any `.refitter` file included to the project as `AdditionalFiles`.
The generator can automatically detect all `.refitter` files inside the project that referenced the `Refitter.SourceGenerator` package and there is no need to include them manually as `AdditionalFiles`
# Using the generated code
Here's an example generated output from the [Swagger Petstore example](https://petstore3.swagger.io) using the default settings
**CLI Tool**
```bash
refitter ./openapi.json --namespace "Your.Namespace.Of.Choice.GeneratedCode"
```
**Source Generator ***.refitter*** file**
```json
{
"openApiPath": "./openapi.json",
"namespace": "Your.Namespace.Of.Choice.GeneratedCode"
}
```
**Output (Snippet)**
Full output is available [here](docs/DefaultOutput.cs)
```cs
using Refit;
using System.Collections.Generic;
using System.Text.Json.Serialization;
using System.Threading.Tasks;
namespace Your.Namespace.Of.Choice.GeneratedCode
{
[System.CodeDom.Compiler.GeneratedCode("Refitter", "1.0.0.0")]
public partial interface ISwaggerPetstore
{
/// Update an existing pet
/// Update an existing pet by Id
/// Update an existent pet in the store
/// Successful operation
///
/// Thrown when the request returns a non-success status code:
///
///
/// Status
/// Description
///
///
/// 400
/// Invalid ID supplied
///
///
/// 404
/// Pet not found
///
///
/// 405
/// Validation exception
///
///
///
[Headers("Accept: application/xml, application/json")]
[Put("/pet")]
Task UpdatePet([Body] Pet body);
...
}
}
```
Here's an example generated output from the [Swagger Petstore example](https://petstore3.swagger.io) configured to wrap the return type in `IApiResponse`
**CLI Tool**
```bash
refitter ./openapi.json --namespace "Your.Namespace.Of.Choice.GeneratedCode" --use-api-response
```
**Source Generator ***.refitter*** file**
```json
{
"openApiPath": "./openapi.json",
"namespace": "Your.Namespace.Of.Choice.GeneratedCode",
"returnIApiResponse": true
}
```
**Output (Snippet)**
Full output is available [here](docs/IApiResponseOutput.cs)
```cs
using Refit;
using System.Collections.Generic;
using System.Text.Json.Serialization;
using System.Threading.Tasks;
namespace Your.Namespace.Of.Choice.GeneratedCode
{
[System.CodeDom.Compiler.GeneratedCode("Refitter", "1.0.0.0")]
public partial interface ISwaggerPetstore
{
/// Update an existing pet
/// Update an existing pet by Id
/// Update an existent pet in the store
///
/// A representing the instance containing the result:
///
///
/// Status
/// Description
///
///
/// 200
/// Successful operation
///
///
/// 400
/// Invalid ID supplied
///
///
/// 404
/// Pet not found
///
///
/// 405
/// Validation exception
///
///
///
[Headers("Accept: application/xml, application/json")]
[Put("/pet")]
Task> UpdatePet([Body] Pet body);
...
}
}
```
Here's an example generated output from the [Swagger Petstore example](https://petstore3.swagger.io) configured to generate an interface for each endpoint
**CLI Tool**
```bash
refitter ./openapi.json --namespace "Your.Namespace.Of.Choice.GeneratedCode" --multiple-interfaces ByEndpoint
```
**Source Generator ***.refitter*** file**
```json
{
"openApiPath": "./openapi.json",
"namespace": "Your.Namespace.Of.Choice.GeneratedCode",
"multipleInterfaces": "ByEndpoint"
}
```
**Output (Snippet)**
Full output is available [here](docs/IApiResponseOutput.cs)
```cs
/// Update an existing pet
[System.CodeDom.Compiler.GeneratedCode("Refitter", "1.0.0.0")]
public partial interface IUpdatePetEndpoint
{
/// Update an existing pet
/// Update an existing pet by Id
/// Update an existent pet in the store
/// Successful operation
///
/// Thrown when the request returns a non-success status code:
///
///
/// Status
/// Description
///
///
/// 400
/// Invalid ID supplied
///
///
/// 404
/// Pet not found
///
///
/// 405
/// Validation exception
///
///
///
[Headers("Accept: application/xml, application/json")]
[Put("/pet")]
Task Execute([Body] Pet body);
}
```
Here's an example generated output from the [Swagger Petstore example](https://petstore3.swagger.io) configured to generate an interface with dynamic querystring parameters
**CLI Tool**
```bash
refitter ./openapi.json --namespace "Your.Namespace.Of.Choice.GeneratedCode" --use-dynamic-querystring-parameters
```
**Output (Snippet)**
Full output is available [here](docs/DynamicQueryStringParameters.cs)
```cs
[System.CodeDom.Compiler.GeneratedCode("Refitter", "1.0.0.0")]
public partial interface ISwaggerPetstoreOpenAPI30
{
/// Updates a pet in the store with form data
/// ID of pet that needs to be updated
/// The dynamic querystring parameter wrapping all others.
/// A that completes when the request is finished.
///
/// Thrown when the request returns a non-success status code:
///
///
/// Status
/// Description
///
///
/// 405
/// Invalid input
///
///
///
[Post("/pet/{petId}")]
Task UpdatePetWithForm(long petId, [Query] UpdatePetWithFormQueryParams queryParams);
}
public class UpdatePetWithFormQueryParams
{
///
/// Name of pet that needs to be updated
///
[Query]
public string Name { get; set; }
///
/// Status of pet that needs to be updated
///
[Query]
public string Status { get; set; }
}
```
## RestService
Here's an example usage of the generated code above
```cs
using Refit;
using System;
using System.Threading.Tasks;
namespace Your.Namespace.Of.Choice.GeneratedCode;
internal class Program
{
private static async Task Main(string[] args)
{
var client = RestService.For("https://petstore3.swagger.io/api/v3");
var pet = await client.GetPetById(1);
Console.WriteLine("## Using Task as return type ##");
Console.WriteLine($"Name: {pet.Name}");
Console.WriteLine($"Category: {pet.Category.Name}");
Console.WriteLine($"Status: {pet.Status}");
Console.WriteLine();
var client2 = RestService.For("https://petstore3.swagger.io/api/v3");
var response = await client2.GetPetById(2);
Console.WriteLine("## Using Task> as return type ##");
Console.WriteLine($"HTTP Status Code: {response.StatusCode}");
Console.WriteLine($"Name: {response.Content.Name}");
Console.WriteLine($"Category: {response.Content.Category.Name}");
Console.WriteLine($"Status: {response.Content.Status}");
}
}
```
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:
```
## Using Task as return type ##
Name: Gatitotototo
Category: Chaucito
Status: Sold
## Using Task> as return type ##
HTTP Status Code: OK
Name: Gatitotototo
Category: Chaucito
Status: Sold
```
## ASP.NET Core and HttpClientFactory
Here's an example Minimal API with the [`Refit.HttpClientFactory`](https://www.nuget.org/packages/Refit.HttpClientFactory) library:
```cs
using Refit;
using Your.Namespace.Of.Choice.GeneratedCode;
var builder = WebApplication.CreateBuilder(args);
builder.Services.AddEndpointsApiExplorer();
builder.Services.AddSwaggerGen();
builder.Services
.AddRefitClient()
.ConfigureHttpClient(c => c.BaseAddress = new Uri("https://petstore3.swagger.io/api/v3"));
var app = builder.Build();
app.MapGet(
"/pet/{id:long}",
async (ISwaggerPetstore petstore, long id) =>
{
try
{
return Results.Ok(await petstore.GetPetById(id));
}
catch (Refit.ApiException e)
{
return Results.StatusCode((int)e.StatusCode);
}
})
.WithName("GetPetById")
.WithOpenApi();
app.UseHttpsRedirection();
app.UseSwaggerUI();
app.UseSwagger();
app.Run();
```
.NET Core supports registering the generated `ISwaggerPetstore` interface via `HttpClientFactory`
The following request to the API above
```shell
curl -X 'GET' 'https://localhost:5001/pet/1' -H 'accept: application/json'
```
Returns a response that looks something like this:
```json
{
"id": 1,
"name": "Special_char_owner_!@#$^&()`.testing",
"photoUrls": [
"https://petstore3.swagger.io/resources/photos/623389095.jpg"
],
"tags": [],
"status": "Sold"
}
```
## 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:
```json
{
"openApiPath": "../OpenAPI/v3.0/petstore.json",
"namespace": "Petstore",
"dependencyInjectionSettings": {
"baseUrl": "https://petstore3.swagger.io/api/v3",
"httpMessageHandlers": [ "TelemetryDelegatingHandler" ],
"transientErrorHandler": "Polly",
"maxRetryCount": 3,
"firstBackoffRetryInSeconds": 0.5
}
}
```
which will generate an extension method to `IServiceCollection` called `ConfigureRefitClients()`. The generated extension method depends on [`Refit.HttpClientFactory`](https://www.nuget.org/packages/Refit.HttpClientFactory) library and looks like this:
```cs
public static IServiceCollection ConfigureRefitClients(
this IServiceCollection services,
Action? builder = default,
RefitSettings? settings = default)
{
var clientBuilderISwaggerPetstore = services
.AddRefitClient(settings)
.ConfigureHttpClient(c => c.BaseAddress = new Uri("https://petstore3.swagger.io/api/v3"))
.AddHttpMessageHandler();
clientBuilderISwaggerPetstore
.AddPolicyHandler(
HttpPolicyExtensions
.HandleTransientHttpError()
.WaitAndRetryAsync(
Backoff.DecorrelatedJitterBackoffV2(
TimeSpan.FromSeconds(0.5),
3)));
builder?.Invoke(clientBuilderISwaggerPetstore);
return services;
}
```
This comes in handy especially when generating multiple interfaces, by tag or endpoint. For example, the following `.refitter` settings file
```json
{
"openApiPath": "../OpenAPI/v3.0/petstore.json",
"namespace": "Petstore",
"multipleInterfaces": "ByTag",
"dependencyInjectionSettings": {
"baseUrl": "https://petstore3.swagger.io/api/v3",
"httpMessageHandlers": [ "TelemetryDelegatingHandler" ],
"transientErrorHandler": "Polly",
"maxRetryCount": 3,
"firstBackoffRetryInSeconds": 0.5
}
}
```
Will generate a single `ConfigureRefitClients()` extension methods that may contain dependency injection configuration code for multiple interfaces like this
```csharp
public static IServiceCollection ConfigureRefitClients(
this IServiceCollection services,
Action? builder = default,
RefitSettings? settings = default)
{
var clientBuilderIPetApi = services
.AddRefitClient(settings)
.ConfigureHttpClient(c => c.BaseAddress = new Uri("https://petstore3.swagger.io/api/v3"))
.AddHttpMessageHandler();
clientBuilderIPetApi
.AddPolicyHandler(
HttpPolicyExtensions
.HandleTransientHttpError()
.WaitAndRetryAsync(
Backoff.DecorrelatedJitterBackoffV2(
TimeSpan.FromSeconds(0.5),
3)));
builder?.Invoke(clientBuilderIPetApi);
var clientBuilderIStoreApi = services
.AddRefitClient(settings)
.ConfigureHttpClient(c => c.BaseAddress = new Uri("https://petstore3.swagger.io/api/v3"))
.AddHttpMessageHandler();
clientBuilderIStoreApi
.AddPolicyHandler(
HttpPolicyExtensions
.HandleTransientHttpError()
.WaitAndRetryAsync(
Backoff.DecorrelatedJitterBackoffV2(
TimeSpan.FromSeconds(0.5),
3)));
builder?.Invoke(clientBuilderIStoreApi);
var clientBuilderIUserApi = services
.AddRefitClient(settings)
.ConfigureHttpClient(c => c.BaseAddress = new Uri("https://petstore3.swagger.io/api/v3"))
.AddHttpMessageHandler();
clientBuilderIUserApi
.AddPolicyHandler(
HttpPolicyExtensions
.HandleTransientHttpError()
.WaitAndRetryAsync(
Backoff.DecorrelatedJitterBackoffV2(
TimeSpan.FromSeconds(0.5),
3)));
builder?.Invoke(clientBuilderIUserApi);
return services;
}
```
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](https://www.apizr.net) 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 definitely free to use the formatted interface with Apizr by registering, configuring and using it following the [Apizr documentation](https://www.apizr.net). 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](#tab/tabid-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:
```json
{
"openApiPath": "../OpenAPI/v3.0/petstore.json",
"namespace": "Petstore",
"useDynamicQuerystringParameters": true,
"dependencyInjectionSettings": {
"baseUrl": "https://petstore3.swagger.io/api/v3",
"httpMessageHandlers": [ "MyDelegatingHandler" ],
"transientErrorHandler": "HttpResilience",
"maxRetryCount": 3,
"firstBackoffRetryInSeconds": 0.5
},
"apizrSettings": {
"withRequestOptions": true, // Recommended to include an Apizr request options parameter to Refit interface methods
"withRegistrationHelper": true, // Mandatory to actually generate the Apizr registration extended method
"withCacheProvider": "InMemory", // Optional, default is None
"withPriority": true, // Optional, default is false
"withMediation": true, // Optional, default is false
"withOptionalMediation": true, // Optional, default is false
"withMappingProvider": "AutoMapper", // Optional, default is None
"withFileTransfer": true // Optional, default is false
}
}
```
which will generate an extension method to `IServiceCollection` called `ConfigurePetstoreApiApizrManager()`. The generated extension method depends on [`Apizr.Extensions.Microsoft.DependencyInjection`](https://www.nuget.org/packages/Apizr.Extensions.Microsoft.DependencyInjection) library and looks like this:
```cs
public static IServiceCollection ConfigurePetstoreApiApizrManager(
this IServiceCollection services,
Action? optionsBuilder = null)
{
optionsBuilder ??= _ => { }; // Default empty options if null
optionsBuilder += options => options
.WithBaseAddress("https://petstore3.swagger.io/api/v3", ApizrDuplicateStrategy.Ignore)
.WithDelegatingHandler()
.ConfigureHttpClientBuilder(builder => builder
.AddStandardResilienceHandler(config =>
{
config.Retry = new HttpRetryStrategyOptions
{
UseJitter = true,
MaxRetryAttempts = 3,
Delay = TimeSpan.FromSeconds(0.5)
};
}))
.WithInMemoryCacheHandler()
.WithAutoMapperMappingHandler()
.WithPriority()
.WithOptionalMediation()
.WithFileTransferOptionalMediation();
return services.AddApizrManagerFor(optionsBuilder);
}
```
This comes in handy especially when generating multiple interfaces, by tag or endpoint. For example, the following `.refitter` settings file
```json
{
"openApiPath": "../OpenAPI/v3.0/petstore.json",
"namespace": "Petstore",
"useDynamicQuerystringParameters": true,
"multipleInterfaces": "ByTag",
"naming": {
"useOpenApiTitle": false,
"interfaceName": "Petstore"
},
"dependencyInjectionSettings": {
"baseUrl": "https://petstore3.swagger.io/api/v3",
"httpMessageHandlers": [ "MyDelegatingHandler" ],
"transientErrorHandler": "HttpResilience",
"maxRetryCount": 3,
"firstBackoffRetryInSeconds": 0.5
},
"apizrSettings": {
"withRequestOptions": true, // Recommended to include an Apizr request options parameter to Refit interface methods
"withRegistrationHelper": true, // Mandatory to actually generate the Apizr registration extended method
"withCacheProvider": "InMemory", // Optional, default is None
"withPriority": true, // Optional, default is false
"withMediation": true, // Optional, default is false
"withOptionalMediation": true, // Optional, default is false
"withMappingProvider": "AutoMapper", // Optional, default is None
"withFileTransfer": true // Optional, default is false
}
}
```
Will generate a single `ConfigurePetstoreApizrManagers()` extension method that may contain dependency injection configuration code for multiple interfaces like this
```csharp
public static IServiceCollection ConfigurePetstoreApizrManagers(
this IServiceCollection services,
Action? optionsBuilder = null)
{
optionsBuilder ??= _ => { }; // Default empty options if null
optionsBuilder += options => options
.WithBaseAddress("https://petstore3.swagger.io/api/v3", ApizrDuplicateStrategy.Ignore)
.WithDelegatingHandler()
.ConfigureHttpClientBuilder(builder => builder
.AddStandardResilienceHandler(config =>
{
config.Retry = new HttpRetryStrategyOptions
{
UseJitter = true,
MaxRetryAttempts = 3,
Delay = TimeSpan.FromSeconds(0.5)
};
}))
.WithInMemoryCacheHandler()
.WithAutoMapperMappingHandler()
.WithPriority()
.WithOptionalMediation()
.WithFileTransferOptionalMediation();
return services.AddApizr(
registry => registry
.AddManagerFor()
.AddManagerFor()
.AddManagerFor(),
optionsBuilder);
}
```
Here, `IPetApi`, `IStoreApi` and `IUserApi` are the generated interfaces which share the same common configuration defined from the `.refitter` file.
### [Static](#tab/tabid-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:
```json
{
"openApiPath": "../OpenAPI/v3.0/petstore.json",
"namespace": "Petstore",
"useDynamicQuerystringParameters": true,
"apizrSettings": {
"withRequestOptions": true, // Recommended to include an Apizr request options parameter to Refit interface methods
"withRegistrationHelper": true, // Mandatory to actually generate the Apizr registration extended method
"withCacheProvider": "Akavache", // Optional, default is None
"withPriority": true, // Optional, default is false
"withMappingProvider": "AutoMapper", // Optional, default is None
"withFileTransfer": true // Optional, default is false
}
}
```
which will generate a static builder method called `BuildPetstore30ApizrManager()`. The generated builder method depends on [`Apizr`](https://www.nuget.org/packages/Apizr) library and looks like this:
```cs
public static IApizrManager BuildPetstore30ApizrManager(Action optionsBuilder)
{
optionsBuilder ??= _ => { }; // Default empty options if null
optionsBuilder += options => options
.WithAkavacheCacheHandler()
.WithAutoMapperMappingHandler(new MapperConfiguration(config => { /* YOUR_MAPPINGS_HERE */ }))
.WithPriority();
return ApizrBuilder.Current.CreateManagerFor(optionsBuilder);
}
```
This comes in handy especially when generating multiple interfaces, by tag or endpoint. For example, the following `.refitter` settings file
```json
{
"openApiPath": "../OpenAPI/v3.0/petstore.json",
"namespace": "Petstore",
"useDynamicQuerystringParameters": true,
"multipleInterfaces": "ByTag",
"naming": {
"useOpenApiTitle": false,
"interfaceName": "Petstore"
},
"dependencyInjectionSettings": {
"baseUrl": "https://petstore3.swagger.io/api/v3",
"httpMessageHandlers": [ "MyDelegatingHandler" ],
"transientErrorHandler": "HttpResilience",
"maxRetryCount": 3,
"firstBackoffRetryInSeconds": 0.5
},
"apizrSettings": {
"withRequestOptions": true, // Recommended to include an Apizr request options parameter to Refit interface methods
"withRegistrationHelper": true, // Mandatory to actually generate the Apizr registration extended method
"withCacheProvider": "InMemory", // Optional, default is None
"withPriority": true, // Optional, default is false
"withMediation": true, // Optional, default is false
"withOptionalMediation": true, // Optional, default is false
"withMappingProvider": "AutoMapper", // Optional, default is None
"withFileTransfer": true // Optional, default is false
}
}
```
Will generate a single `BuildPetstoreApizrManagers()` builder method that may contain configuration code for multiple interfaces like this
```csharp
public static IApizrRegistry BuildPetstoreApizrManagers(Action optionsBuilder)
{
optionsBuilder ??= _ => { }; // Default empty options if null
optionsBuilder += options => options
.WithAkavacheCacheHandler()
.WithAutoMapperMappingHandler(new MapperConfiguration(config => { /* YOUR_MAPPINGS_HERE */ }))
.WithPriority();
return ApizrBuilder.Current.CreateRegistry(
registry => registry
.AddManagerFor()
.AddManagerFor()
.AddManagerFor(),
optionsBuilder);
}
```
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` parameter while calling the generated method.
To know how to make Apizr fit your needs, please refer to the [Apizr documentation](https://www.apizr.net).
### Using the managers
Once you called the generated method, you will get an `IApizrManager` instance that you can use to make requests to the API. Here's an example of how to use it:
```csharp
var result = await petstoreManager.ExecuteAsync((api, opt) => api.GetPetById(1, opt),
options => options // Whatever final request options you want to apply
.WithPriority(Priority.Background)
.WithHeaders(["HeaderKey1: HeaderValue1"])
.WithRequestTimeout("00:00:10")
.WithCancellation(cts.Token));
```
Please head to the [Apizr documentation](https://www.apizr.net) to get more.
## System requirements
.NET 8.0 or .NET 9.0
## Testing
Refitter uses [TUnit](https://github.com/thomhurst/TUnit) as its testing framework instead of xUnit. TUnit was chosen for its superior performance, providing 3x faster test execution compared to xUnit. This significantly improves the developer experience when running the test suite locally and in CI/CD pipelines.
To run the tests:
```bash
dotnet test --solution src/Refitter.slnx -c Release
```
## Contributing
Please read our [contribution guidelines](CONTRIBUTING.md) if you'd like to contribute to the project.
## Contributors
Philip Cox
π»
Cameron MacFarland
π»
kgame
π»
Thomas Pettersen / Yrki
π»
Artem
π
m7clarke
π
kirides
π π»
guillaumeserale
π» π
Dennis Brentjes
π» π€
Damian Hickey
π
richardhu-lmg
π
brease-colin
π
angelofb
π»
Dim Nogro
π»
yadanilov19
π€ π»
Daniel Powell
π
Ekkeir
π π
Waylon Martinez
π
vkmadupa
π
Noblix
π» π€
Attila Hajdrik
π€
bielik01
π π€
naaeef
π€
Alireza Habibi
π
Jeff Parker, PE
π
jods
π€ π
Edimarquez Medeiros
π»
safakkesikci
π
folbrecht
π
mortenlaursen
π»
manuel-fernandez-rodriguez
π
Eli Yammine
π
kami-poi
π€
Xeevis
π
DJ4ddi
π» π€
direncancatalkaya
π»
Robert Palmqvist
π€ π»
Tim M
π
janfolbrecht
π€ π»
Nick Seguin
π»
David Brink
π π»
Stu Wilson
π€ π»
sharpzilla
π€
Tatu
π
JΓ©rΓ©my BRUN-PICARD
π€ π» π
Ed Barnard
π€
bastien.noel
π
Meikel Philipp
π€
Berk Selvi
π€ π»
Joshua Ozeri
π
Ryan Heath
π€ π»
Brian Brunner
π€
Frank Samiec
π»
Fabio Loreggian
π
geometrikal
π
Shubin Pavel
π»
Wiebe Tijsma
π€
Henri Demers
π
Amund
π» π
Vegard LΓΈkken
π» π
brad-technologik
π
JarosΕaw Dutka
π»
maksionkin
π
wocasella
π
Petr Zika
π
Sebastian Wachsmuth
π»
qrzychu
π
ΠΠ»Π΅ΠΊΡΠ°Π½Π΄Ρ
π
AragornHL
π»
kmfd3s
π»
Philipp Feigl
π
Tommi Haapa
π
Scott Taylor
π
sb-chericks
π€ π
Staffan WΓ€rnberg
π
Linus Hamlin
π π»
Marco Hernandez
π π€
david-pw
π π»
eoma-knowit
π»
CΓ©dric Luthi
π»
Christoph De Baene
π
7amou3
π€
Halden
π€
mhartmair-cubido
π
Keith Roberts
π
Kenneth Crawford
π€ π»
0x2badc0de
π
Tylor Pater
π»
#
For tips and tricks on software development, check out [my blog](https://christianhelle.com)
If you find this useful and feel a bit generous then feel free to [buy me a coffee β](https://www.buymeacoffee.com/christianhelle)