.Refitter File format

The .refitter file is a JSON serialized version of the RefitGeneratorSettings

The following is an example .refitter file

{
  "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
  "generateXmlDocCodeComments": true, // Optional. Default=true
  "generateStatusCodeComments": true, // Optional. Default=true
  "addAutoGeneratedHeader": true, // Optional. Default=true
  "addAcceptHeaders": 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
  "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
  "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. Automatically set to true if contractsOutputFolder is specified. Default=false
  "additionalNamespaces": [ // Optional
    "Namespace1",
    "Namespace2"
  ],
  "excludeNamespaces": [ // Optional. Exclude namespaces that match the provided regular expressions
    "^Namespace[.].*",
    "^Namespace$"
  ],
  "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.+"
  ],
  "generateDefaultAdditionalProperties": true, // Optional. default=true
  "operationNameGenerator": "Default", // Optional. May be one of Default, MultipleClientsFromOperationId, MultipleClientsFromPathSegments, MultipleClientsFromFirstTagAndOperationId, MultipleClientsFromFirstTagAndOperationName, MultipleClientsFromFirstTagAndPathSegments, SingleClientFromOperationId, SingleClientFromPathSegments
  "immutableRecords": false,
  "useDynamicQuerystringParameters": false, // Optional. Default=false
  "usePolymorphicSerialization": false, // 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": false, // Optional. Default=false
    "withCacheProvider": "None", // Optional. Values=None|Akavache|MonkeyCache|InMemory|DistributedAsString|DistributedAsByteArray. Default=None
    "withPriority": false, // Optional. Default=false
    "withMediation": false, // Optional. Default=false
    "withOptionalMediation": false, // Optional. Default=false
    "withMappingProvider": "None", // Optional. Values=None|AutoMapper|Mapster. Default=None
    "withFileTransfer": false // 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",
    "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,
    "excludedTypeNames": [
      "ExcludedTypeFoo",
      "ExcludedTypeBar"
    ]
  }
}

Descriptions

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
contractsNamespace - the namespace used in the generated contracts. If not specified, this defaults to what namespace is set to
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.
contractsOutputFolder - a string describing a relative path to a desired output folder for the Contrats.cs file. By the default, this uses the value specified in outputFolder
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.
usePolymorphicSerialization: Set to true to use System.Text.Json polymorphic serialization.
generateMultipleFiles: Set to true to generate multiple files. This is automatically set to true when ContractsOutputFolder is specified. Refit interface(s) are written to a file called RefitInterfaces.cs, Contracts are written to a file called Contracts.cs, and Dependency Injection is written to a file called DependencyInjection.cs
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 - (DEPRECATED) Set this to true to configure the HttpClient to use Polly using a retry policy with a jittered backoff
- transientErrorHandler: Set this to configure transient error handling with a retry policy that uses a jittered backoff. See https://refitter.github.io/api/Refitter.Core.TransientErrorHandler.html
- 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,
- generateNativeRecords - Default is false
- generateDefaultValues - Default is true
- inlineNamedAny - Default is false
- excludedTypeNames - Default is empty

JSON Schema

{
    "$schema": "http://json-schema.org/draft-07/schema#",
    "type": "object",
    "properties": {
        "openApiPath": {
            "type": "string",
            "description": "The path to the OpenAPI specification file."
        },
        "namespace": {
            "type": "string",
            "description": "The namespace for the generated code."
        },
        "contractsNamespace": {
            "type": "string",
            "description": "The namespace for the generated contracts code."
        },
        "naming": {
            "type": "object",
            "properties": {
                "useOpenApiTitle": {
                    "type": "boolean",
                    "description": "Indicates whether to use the OpenAPI title for naming."
                },
                "interfaceName": {
                    "type": "string",
                    "description": "The name of the generated interface."
                }
            }
        },
        "generateContracts": {
            "type": "boolean",
            "description": "Indicates whether to generate contracts."
        },
        "generateXmlDocCodeComments": {
            "type": "boolean",
            "description": "Indicates whether to generate XML documentation code comments."
        },
        "addAutoGeneratedHeader": {
            "type": "boolean",
            "description": "Indicates whether to add an auto-generated header."
        },
        "addAcceptHeaders": {
            "type": "boolean",
            "description": "Indicates whether to add accept headers."
        },
        "returnIApiResponse": {
            "type": "boolean",
            "description": "Indicates whether to return IApiResponse."
        },
        "responseTypeOverride": {
            "type": "object",
            "additionalProperties": {
                "type": "string"
            },
            "description": "Overrides the response type for specific status codes."
        },
        "generateOperationHeaders": {
            "type": "boolean",
            "description": "Indicates whether to generate operation headers."
        },
        "typeAccessibility": {
            "type": "string",
            "enum": [
                "Public",
                "Internal"
            ],
            "description": "The accessibility level for generated types."
        },
        "useCancellationTokens": {
            "type": "boolean",
            "description": "Indicates whether to use cancellation tokens."
        },
        "useIsoDateFormat": {
            "type": "boolean",
            "description": "Indicates whether to use ISO date format."
        },
        "multipleInterfaces": {
            "type": "string",
            "enum": [
                "ByEndpoint",
                "ByTag"
            ],
            "description": "Specifies how to generate multiple interfaces."
        },
        "outputFolder": {
            "type": "string",
            "description": "The output folder for the generated code."
        },
        "outputFilename": {
            "type": "string",
            "description": "The output filename for the generated code."
        },
        "contractsOutputFolder": {
            "type": "string",
            "description": "The output folder for the generated contracts code",
        },
        "additionalNamespaces": {
            "type": "array",
            "items": {
                "type": "string"
            },
            "description": "Additional namespaces to include in the generated code."
        },
        "excludeNamespaces": {
          "type": "array",
          "items": {
              "type": "string"
          },
          "description": "Exclude namespaces that match the provided regular expressions."
        },
        "includeTags": {
            "type": "array",
            "items": {
                "type": "string"
            },
            "description": "Tags to include in the generation process."
        },
        "includePathMatches": {
            "type": "array",
            "items": {
                "type": "string"
            },
            "description": "Path patterns to include in the generation process."
        },
        "generateDeprecatedOperations": {
            "type": "boolean",
            "description": "Indicates whether to generate deprecated operations."
        },
        "operationNameTemplate": {
            "type": "string",
            "description": "The template for generating operation names."
        },
        "optionalParameters": {
            "type": "boolean",
            "description": "Indicates whether to include optional parameters."
        },
        "trimUnusedSchema": {
            "type": "boolean",
            "description": "Indicates whether to trim unused schema."
        },
        "keepSchemaPatterns": {
            "type": "array",
            "items": {
                "type": "string"
            },
            "description": "Patterns to keep in the schema."
        },
        "generateDefaultAdditionalProperties": {
            "type": "boolean",
            "description": "Indicates whether to generate default additional properties."
        },
        "operationNameGenerator": {
            "type": "string",
            "description": "The generator used to generate operation names."
        },
        "immutableRecords": {
            "type": "boolean",
            "description": "Set to true to generate contracts as immutable records instead of classes"
        },
        "useDynamicQuerystringParameters": {
            "type": "boolean",
            "description": "Set to true to wrap multiple query parameters into a single complex one."
        },
        "usePolymorphicSerialization": {
            "type": "boolean",
            "description": "Set to true to use System.Text.Json polymorphic serialization"
        },
        "generateMultipleFiles": {
            "type": "boolean",
            "description": "Set to `true` to generate multiple files. This is automatically set to `true` when `ContractsOutputFolder` is specified. Refit interface(s) are written to a file called `RefitInterfaces.cs`, Contracts are written to a file called `Contracts.cs`, and Dependency Injection is written to a file called `DependencyInjection.cs`"
        },
        "dependencyInjectionSettings": {
            "type": "object",
            "properties": {
                "baseUrl": {
                    "type": "string",
                    "description": "The base URL for the dependency injection settings."
                },
                "httpMessageHandlers": {
                    "type": "array",
                    "items": {
                        "type": "string"
                    },
                    "description": "HTTP message handlers for the dependency injection settings."
                },
                "usePolly": {
                    "type": "boolean",
                    "description": "Indicates whether to use Polly for the dependency injection settings."
                },
                "maxRetryCount": {
                    "type": "integer",
                    "description": "The maximum retry count for Polly in the dependency injection settings."
                },
                "firstBackoffRetryInSeconds": {
                    "type": "integer",
                    "description": "The first backoff retry in seconds for the dependency injection settings."
                }
            },
            "description": "Settings for dependency injection."
        },
        "apizrSettings": {
            "type": "object",
            "properties": {
                "withRequestOptions": {
                    "type": "boolean",
                    "description": "Tells if the Refit interface methods should have a final IApizrRequestOptions options parameter."
                },
                "withRegistrationHelper": {
                    "type": "boolean",
                    "description": "Tells if Refitter should generate Apizr registration helpers (extended with dependencyInjectionSettings set, otherwise static)."
                },
                "withCacheProvider": {
                    "type": "string",
                    "enum": [
                        "None",
                        "Akavache",
                        "MonkeyCache",
                        "InMemory",
                        "DistributedAsString",
                        "DistributedAsByteArray"
                    ],
                    "description": "Set the cache provider to be used."
                },
                "withPriority": {
                    "type": "boolean",
                    "description": "Tells if Apizr should handle request priority."
                },
                "withMediation": {
                    "type": "boolean",
                    "description": "Tells if Apizr should handle request mediation (extended only)."
                },
                "withOptionalMediation": {
                    "type": "boolean",
                    "description": "Tells if Apizr should handle optional request mediation (extended only)."
                },
                "withMappingProvider": {
                    "type": "string",
                    "enum": [
                        "None",
                        "AutoMapper",
                        "Mapster"
                    ],
                    "description": "Set the mapping provider to be used."
                },
                "withFileTransfer": {
                    "type": "boolean",
                    "description": "Tells if Apizr should handle file transfer."
                }
            },
            "description": "Settings for Apizr."
        },
        "codeGeneratorSettings": {
            "type": "object",
            "properties": {
                "requiredPropertiesMustBeDefined": {
                    "type": "boolean",
                    "description": "Indicates whether required properties must be defined in the code generator settings."
                },
                "generateDataAnnotations": {
                    "type": "boolean",
                    "description": "Indicates whether to generate data annotations in the code generator settings."
                },
                "anyType": {
                    "type": "string",
                    "description": "The type used for 'any' in the code generator settings."
                }
            },
            "description": "Settings for the code generator."
        }
    }
}

Table of Contents

.Refitter File format

Descriptions

JSON Schema