Refitter.SourceGenerator 0.9.4.43-preview

This is a prerelease version of Refitter.SourceGenerator.
There is a newer version of this package available.
See the version list below for details.
dotnet add package Refitter.SourceGenerator --version 0.9.4.43-preview                
NuGet\Install-Package Refitter.SourceGenerator -Version 0.9.4.43-preview                
This command is intended to be used within the Package Manager Console in Visual Studio, as it uses the NuGet module's version of Install-Package.
<PackageReference Include="Refitter.SourceGenerator" Version="0.9.4.43-preview">
  <PrivateAssets>all</PrivateAssets>
  <IncludeAssets>runtime; build; native; contentfiles; analyzers</IncludeAssets>
</PackageReference>                
For projects that support PackageReference, copy this XML node into the project file to reference the package.
paket add Refitter.SourceGenerator --version 0.9.4.43-preview                
#r "nuget: Refitter.SourceGenerator, 0.9.4.43-preview"                
#r directive can be used in F# Interactive and Polyglot Notebooks. Copy this into the interactive tool or source code of the script to reference the package.
// Install Refitter.SourceGenerator as a Cake Addin
#addin nuget:?package=Refitter.SourceGenerator&version=0.9.4.43-preview&prerelease

// Install Refitter.SourceGenerator as a Cake Tool
#tool nuget:?package=Refitter.SourceGenerator&version=0.9.4.43-preview&prerelease                

Source Generator

Refitter is available as a C# Source Generator that uses the Refitter.Core library for generating a REST API Client using the Refit library. Refitter can generate the Refit interface from OpenAPI specifications

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

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

.Refitter File format

The following is an example .refitter file

{
  "openApiPath": "/path/to/your/openAPI", // Required
  "namespace": "Org.System.Service.Api.GeneratedCode", // 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
  "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/.*"
  ],
  "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, // Optional. Set this to true, to configure Polly with a retry policy that uses a jittered backoff. Default=false
    "pollyMaxRetryCount": 3, // Optional. Default=6
    "firstBackoffRetryInSeconds": 0.5 // Optional. Default=1.0
  },
  "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"
    ]
  }
}
  • 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
  • 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 "multipleIinterfaces": "ByEndpoint", This is name of the Execute() method in the interface
  • optionalParameters - Generate non-required parameters as nullable optional parameters
  • 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
    • pollyMaxRetryCount - 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
  • 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
There are no supported framework assets in this package.

Learn more about Target Frameworks and .NET Standard.

NuGet packages

This package is not used by any NuGet packages.

GitHub repositories (1)

Showing the top 1 popular GitHub repositories that depend on Refitter.SourceGenerator:

Repository Stars
christianhelle/refitter
A tool for generating Refit interfaces and contracts from OpenAPI specifications
Version Downloads Last updated
1.5.0-preview.65 46 12/8/2024
1.5.0-preview.64 41 12/7/2024
1.5.0-preview.63 44 12/7/2024
1.4.1 2,770 11/20/2024
1.4.1-preview.62 49 11/4/2024
1.4.0 4,845 10/14/2024
1.4.0-preview.61 42 10/7/2024
1.3.2 1,533 9/23/2024
1.3.2-preview.60 46 9/23/2024
1.3.1 567 9/20/2024
1.3.0 1,558 9/14/2024
1.2.1-preview.59 57 9/13/2024
1.2.1-preview.58 128 9/11/2024
1.2.1-preview.57 63 9/11/2024
1.2.1-preview.56 55 9/9/2024
1.2.1-preview.55 54 9/2/2024
1.2.1-preview.54 52 8/29/2024
1.2.0 3,061 8/12/2024
1.2.0-preview.53 39 8/4/2024
1.2.0-preview.52 48 7/29/2024
1.1.3 20,368 7/19/2024
1.1.3-preview.51 50 7/19/2024
1.1.2 24,837 7/17/2024 1.1.2 is deprecated because it has critical bugs.
1.1.2-preview.50 44 7/16/2024
1.1.2-preview.49 61 7/11/2024
1.1.1 187,358 7/6/2024
1.1.1-preview.48 49 7/4/2024
1.1.1-preview.47 56 7/1/2024
1.1.1-preview.46 59 6/28/2024
1.1.0.45-preview 97 6/25/2024
1.0.2 237,816 6/13/2024
1.0.1 48,500 6/7/2024
1.0.0 246,663 5/3/2024
0.9.9.44-preview 80 4/29/2024
0.9.9 10,353 3/7/2024
0.9.8 2,091 2/27/2024
0.9.7 73,382 2/7/2024
0.9.6 285 1/29/2024
0.9.5 33,710 1/15/2024
0.9.4.43-preview 157 1/15/2024
0.9.4 32,171 1/12/2024
0.9.3.42-preview 149 1/10/2024
0.9.2 20,213 1/10/2024
0.9.1 4,153 1/9/2024
0.9.0 8,555 1/9/2024
0.8.7.41-preview 160 1/3/2024
0.8.7.40-preview 237 12/20/2023
0.8.7 59,371 12/18/2023
0.8.6.39-preview 443 12/14/2023
0.8.6.38-preview 139 12/14/2023
0.8.6 10,413 12/11/2023
0.8.5 654 11/23/2023
0.8.4 819 11/7/2023
0.8.3 214 10/31/2023
0.8.2 2,417 10/9/2023
0.8.1 230 10/4/2023
0.8.0 7,959 9/23/2023
0.7.5 211 9/7/2023
0.7.4 195 9/6/2023
0.7.3.37-preview 254 8/25/2023
0.7.3.36-preview 161 8/25/2023
0.7.3.35-preview 217 8/21/2023
0.7.3.34-preview 194 8/15/2023
0.7.3.33-preview 333 8/12/2023
0.7.3 887 8/26/2023
0.7.2.32-preview 292 8/7/2023 0.7.2.32-preview is deprecated because it has critical bugs.
0.7.2 271 8/7/2023 0.7.2 is deprecated because it has critical bugs.
0.7.1.31-preview 284 8/2/2023 0.7.1.31-preview is deprecated because it has critical bugs.
0.7.1.30-preview 278 8/2/2023 0.7.1.30-preview is deprecated because it has critical bugs.
0.7.1.29-preview 176 8/1/2023 0.7.1.29-preview is deprecated because it has critical bugs.
0.7.1 245 8/3/2023 0.7.1 is deprecated because it has critical bugs.
0.7.0.28-preview 242 7/28/2023 0.7.0.28-preview is deprecated because it has critical bugs.
0.7.0.27-preview 251 7/28/2023 0.7.0.27-preview is deprecated because it has critical bugs.
0.7.0.26-preview 258 7/27/2023 0.7.0.26-preview is deprecated because it has critical bugs.
0.7.0.23-preview 268 7/27/2023 0.7.0.23-preview is deprecated because it has critical bugs.
0.7.0.22-preview 244 7/27/2023 0.7.0.22-preview is deprecated because it has critical bugs.
0.7.0.21-preview 210 7/27/2023 0.7.0.21-preview is deprecated because it has critical bugs.
0.7.0.20-preview 220 7/27/2023 0.7.0.20-preview is deprecated because it has critical bugs.
0.7.0 179 7/31/2023 0.7.0 is deprecated because it has critical bugs.
0.6.3.10 204 7/26/2023 0.6.3.10 is deprecated because it has critical bugs.
0.6.3.9 183 7/26/2023 0.6.3.9 is deprecated because it has critical bugs.
0.6.3.8 265 7/26/2023 0.6.3.8 is deprecated because it has critical bugs.
0.6.3.7-preview 238 7/26/2023 0.6.3.7-preview is deprecated because it has critical bugs.
0.6.3.6-preview 205 7/26/2023 0.6.3.6-preview is deprecated because it has critical bugs.
0.6.3.5-preview 255 7/26/2023 0.6.3.5-preview is deprecated because it has critical bugs.
0.6.3.4-preview 251 7/26/2023 0.6.3.4-preview is deprecated because it has critical bugs.