Table of Contents

Breaking Changes: v2.0.0

Refitter v2.0.0 introduces 2 breaking changes that require action if you're upgrading from v1.7.3 or earlier. Both changes fix serious bugs and include straightforward migration paths.

Breaking Change #1: Authentication Header Configuration Renamed

Summary

The .refitter authentication setting has been renamed and restructured:

  • Old: "generateAuthenticationHeader" (boolean)
  • New: "authenticationHeaderStyle" (enum: None, Method, Parameter)

Impact

Users with custom authentication headers in their .refitter files must update their configuration. Old JSON keys are silently ignored, causing authentication header generation to be disabled even if your config specifies otherwise.

Migration

Before (v1.7.3):

{
  "openApiPath": "./swagger.json",
  "namespace": "MyApi",
  "generateAuthenticationHeader": true
}

After (v2.0.0):

{
  "openApiPath": "./swagger.json",
  "namespace": "MyApi",
  "authenticationHeaderStyle": "Method"
}

Valid authenticationHeaderStyle values:

  • "None" — No authentication header generation (default)
  • "Method" — Add [Headers("Authorization: Bearer")] to each method
  • "Parameter" — Add authorizationToken parameter to each method

Migration Steps

  1. Search all .refitter files for "generateAuthenticationHeader"
  2. Replace according to your use case:
    • "generateAuthenticationHeader": true → "authenticationHeaderStyle": "Method" or "Parameter"
    • "generateAuthenticationHeader": false → "authenticationHeaderStyle": "None" (or remove the setting)
  3. Rebuild your project to verify the change

Breaking Change #2: Source Generator No Longer Writes Disk Files

Summary

The Refitter.SourceGenerator now uses Roslyn's context.AddSource() API to generate code in-memory instead of writing physical .g.cs files to disk. Generated code is still compiled into your assembly but is not persisted to the file system.

Impact

Users of Refitter.SourceGenerator who:

  • Version-control generated .g.cs files
  • Reference generated files directly in build scripts
  • Expect physical files in the ./Generated folder
  • Relied on Refit flowing transitively from Refitter.SourceGenerator

will need to adjust their workflow.

Why This Change

This fix resolves critical issues:

  • Issue #635: Build errors when combined with Microsoft.Extensions.ApiDescription.Server
  • Issue #520: File locking errors ("The process cannot access the file")
  • Issue #310: Source generator crashes on .NET 8

Migration: Two Options

Generated code remains accessible through your IDE without cluttering the file system:

  • Visual Studio: Right-click .refitter file → Select "View Generated Code"
  • Visual Studio Code: Right-click .refitter file → Select "Peek Generated Code" (requires Roslyn extension)
  • Rider: Right-click .refitter file → Select "View Generated Files"

This is the recommended approach for most users.

Package References for Source Generator Consumers

Refitter.SourceGenerator keeps its Refit dependency private. Add a direct package reference to Refit in every consuming project, and add Refit.HttpClientFactory separately if you use generated dependency-injection helpers such as ConfigureRefitClients().

<ItemGroup>
  <PackageReference Include="Refitter.SourceGenerator" Version="2.0.0" />
  <PackageReference Include="Refit" Version="10.1.6" />
  <PackageReference Include="Refit.HttpClientFactory" Version="10.1.6" />
</ItemGroup>

If you do not use the generated DI helpers, omit Refit.HttpClientFactory.

Option B: Generate Physical Files with CLI or MSBuild

If you need disk files for version control, inspection, or custom build processes:

Using Refitter CLI:

dotnet tool install -g Refitter
refitter ./swagger.json --output ./GeneratedClient.cs --namespace "MyApi"

Using Refitter MSBuild:

<PackageReference Include="Refitter.MSBuild" Version="2.0.0" />

Add .refitter files to your project. MSBuild generates and writes physical files to the configured outputFolder.

Updating CI/CD Pipelines

If your CI/CD pipeline references generated files:

  1. Remove dependencies on generated file paths from disk (e.g., don't copy ./Generated/**/*.g.cs)
  2. Switch to MSBuild or CLI if you need persistent files
  3. Update version-control patterns to remove .g.cs from .gitignore (if using MSBuild) or to ignore them (if using Source Generator)

Silent Behavioral Change: OpenAPI Parser Upgrade

Summary

Refitter v2.0.0 upgrades the OpenAPI parser from Microsoft.OpenApi.Readers 1.x to 3.x (OasReader 3.7.0.20). This is a major version upgrade with materially different schema interpretation.

Impact

Users upgrading from v1.7.3 may see different generated C# code even without changing their OpenAPI specifications. This is not a breaking change in the Refitter API, but a behavioral change in code generation caused by the parser upgrade. The branch proves the parser changed and documents how to migrate; it does not prove full 1.7.3-vs-v2.0 behavioral equivalence across a broad real-world corpus.

What Changed in the Parser

Microsoft.OpenApi 3.x interprets these schema aspects differently than 1.x:

  • Nullability handling: More strict null type interpretation
  • Discriminator support: Improved oneOf/anyOf discriminator resolution
  • Reference resolution: Safer $ref path handling
  • Examples: Better handling of embedded schema examples
  • Swagger 2.0 edge cases: More robust handling of specs without components section

Migration

Action required: After upgrading Refitter to v2.0.0:

  1. Regenerate your client code from your OpenAPI specification
  2. Review the generated code diff carefully
  3. Run your test suite to ensure the new client works correctly
  4. Commit the updated generated code

Treat these steps as the recommended mitigation for the parser upgrade: regenerate, inspect the diff, and validate your client with tests before shipping.

Example

If you're using the CLI:

# Regenerate with new parser
refitter ./swagger.json --output ./GeneratedClient.cs --namespace "MyApi"

# Review the diff
git diff GeneratedClient.cs

# Run tests
dotnet test

# Commit
git add GeneratedClient.cs && git commit -m "Regenerate client with OpenAPI parser v3.x"

If you're using Source Generator or MSBuild, rebuild your project and review the generated changes the same way.

Migration Checklist

  • [ ] Upgrade Refitter to v2.0.0
  • [ ] Regenerate client code from your OpenAPI specification
  • [ ] Review generated code diff for changes caused by the OpenAPI parser upgrade
  • [ ] Update .refitter files: replace generateAuthenticationHeader with authenticationHeaderStyle
  • [ ] If using Refitter.SourceGenerator: add a direct Refit package reference (and Refit.HttpClientFactory if using generated DI helpers)
  • [ ] If using Source Generator: choose IDE viewing or switch to CLI/MSBuild
  • [ ] Run test suite to verify new client behavior
  • [ ] Rebuild and test code generation
  • [ ] Update CI/CD pipelines and build scripts as needed
  • [ ] Remove generated .g.cs files from version control (if using Source Generator)

What's Not Changing

These features remain fully backward compatible:

  • .refitter file format (except auth setting above)
  • CLI tool commands and options
  • MSBuild task integration
  • Generated Refit interface syntax
  • Contract type generation

New Features in v2.0.0

v2.0.0 also includes several new opt-in features with safe defaults:

  • Property Naming: "propertyNamingPolicy": "PreserveOriginal" to keep original OpenAPI property names
  • Multiple Specs: "openApiPaths": ["./swagger1.json", "./swagger2.json"] to merge multiple specifications
  • Contract Suffix: "contractTypeSuffix": "Dto" for custom contract type naming
  • AOT Support: "generateJsonSerializerContext": true for ahead-of-time compilation
  • Bug fixes for recursive schemas, digit-prefixed property names, and multipart forms

Need Help?

If you encounter issues during migration or have questions, please:

  1. Check the full CHANGELOG for a complete list of changes
  2. Review the .refitter file format documentation
  3. Open an issue on GitHub
  4. Start a discussion on GitHub
Edit this page