name: Refitter Vocabulary
description: >-
  Vocabulary for the Refitter .NET code generation tool ecosystem, covering
  concepts related to OpenAPI-to-C# code generation, Refit interfaces,
  and .NET source generators.
version: '1.0'
modified: '2026-05-02'
source: https://refitter.github.io
terms:
  - term: Refitter
    definition: >-
      An open-source .NET tool and Roslyn source generator that reads OpenAPI
      2.0 and 3.x specifications and generates strongly-typed C# Refit HTTP
      client interfaces and model classes. Available as a dotnet global tool
      (dotnet-refitter) and as a NuGet source generator package.
    tags:
      - Tool
      - Core Concept

  - term: Refit
    definition: >-
      A type-safe REST library for .NET that simplifies HTTP API consumption
      by converting C# interface declarations decorated with HTTP attributes
      into working API clients via Castle DynamicProxy or compile-time source
      generation. Refitter generates these interface declarations automatically
      from OpenAPI specifications.
    tags:
      - Library
      - Dependency

  - term: Refit Interface
    definition: >-
      A C# interface where each method represents an HTTP API endpoint,
      decorated with Refit attributes (e.g., [Get("/users")], [Post("/users")],
      [Put("/users/{id}")]) and return types using Task<T> or IApiResponse<T>.
      Refitter generates these interfaces from OpenAPI operation definitions.
    tags:
      - Code Generation
      - Core Concept

  - term: Source Generator
    definition: >-
      A .NET Roslyn compiler feature (introduced in .NET 5) that runs during
      compilation to analyze source code and generate additional C# source
      files. Refitter's source generator reads .refitter configuration files
      and the referenced OpenAPI specs to generate interfaces at build time.
    tags:
      - .NET
      - Core Concept

  - term: .refitter Configuration File
    definition: >-
      A JSON configuration file (typically named *.refitter) that controls
      Refitter's code generation behavior, specifying the OpenAPI spec path,
      namespace, output file name, type style, and other generation options.
      Placed in the .NET project directory to trigger the source generator.
    tags:
      - Configuration

  - term: dotnet-refitter
    definition: >-
      The dotnet global CLI tool distribution of Refitter. Installed via
      `dotnet tool install -g dotnet-refitter`. Invoked as `refitter` on
      the command line to generate code on demand, independent of the
      .NET build pipeline.
    tags:
      - CLI
      - Tool

  - term: Type Style
    definition: >-
      A Refitter setting that controls the C# type to generate for API models.
      Options are Classes (standard C# classes), Records (C# records with
      immutability), and RecordsStruct (value-type records). Defaults to Classes.
    tags:
      - Code Generation
      - Configuration

  - term: IApiResponse
    definition: >-
      A Refit wrapper type that exposes HTTP response metadata (headers, status
      code, error) alongside the deserialized response body. When returnIApiResponse
      is set to true in Refitter, generated methods return IApiResponse<T> instead
      of T, enabling callers to inspect response details.
    tags:
      - Refit
      - API Design

  - term: Multiple Interfaces
    definition: >-
      A Refitter feature (multipleInterfaces setting) that splits the generated
      output into multiple C# interfaces instead of a single monolithic interface.
      Can split ByTag (one interface per OpenAPI tag) or ByEndpoint (one interface
      per path).
    tags:
      - Code Generation
      - Configuration

  - term: NJsonSchema
    definition: >-
      A .NET library for working with JSON Schema that Refitter uses internally
      to parse OpenAPI schemas and generate model classes. NJsonSchema handles
      the translation from OpenAPI schema types to C# types.
    tags:
      - Dependency
      - Schema

  - term: Contract Models
    definition: >-
      The C# model classes or records generated by Refitter to represent
      OpenAPI schema components (request bodies, response types, shared schemas).
      Generated from the components/schemas section of the OpenAPI specification.
    tags:
      - Code Generation

  - term: DI Registration
    definition: >-
      Optional Microsoft.Extensions.DependencyInjection extension methods
      generated by Refitter (when generateDependencyInjectionExtensions is true)
      to register the Refit HttpClient and generated interfaces in the .NET
      service container using AddRefitClient<T>().
    tags:
      - Dependency Injection
      - .NET

  - term: CancellationToken
    definition: >-
      A .NET mechanism for cooperative cancellation of async operations.
      When useCancellationTokens is true in Refitter, a CancellationToken
      parameter is added to all generated async methods, enabling callers
      to cancel in-flight HTTP requests.
    tags:
      - .NET
      - Async