API Reference

📖 API Reference

Reference for all generated extension methods, classes, and types produced by the source generator.

---

🔌 Service Registration Extensions

These extension methods are generated on IServiceCollection for dependency injection setup in Program.cs.

📝 About the {Project} placeholder: {Project} is the last dot-segment of the project/assembly name (e.g. MyCompany.Product.PetStore → PetStore, producing AddPetStoreApi() / MapPetStoreApi()). A trailing Api suffix on that segment is stripped (case-insensitive) so the generated names never double up:

Project name	{Project}	Generated method
MyCompany.Product.PetStore	PetStore	MapPetStoreApi()
MyCompany.Product.Api	(empty)	MapApi() (not MapApiApi())
MyCompany.Product.WebApi	Web	MapWebApi() (not MapWebApiApi())

The same rule applies to Add{Project}Api(), Use{Project}Api(), and Add{Project}ApiVersioning().

Core Registration

Method	Generated When	Description
services.Add{Project}Api()	Always (with useGlobalErrorHandler)	Registers all API services: rate limiting, security policies, handler DI
services.AddApiHandlersFromDomain()	Domain project exists	Registers all handler implementations from the domain assembly
services.AddApiValidatorsFromDomain()	FluentValidation validators exist	Registers all IValidator<T> implementations
services.AddApiHealthChecks()	healthChecks.enabled: true	Registers ASP.NET Core health check services

Feature-Specific Registration

Method	Generated When	Description
services.AddApiResilience()	x-retry-* extensions in spec	Configures Polly resilience policies on IHttpClientFactory
services.AddWebhookHandlersFromDomain()	Webhooks + domain project	Registers webhook handler implementations

---

🛣️ Endpoint Mapping Extensions

These extension methods are generated on WebApplication for mapping API endpoints in Program.cs.

Core Mapping

Method	Generated When	Description
app.Map{Project}Api()	Always (with useGlobalErrorHandler)	Maps all endpoints + configures middleware (rate limiter, auth, error handling)
app.Map{Segment}Endpoints()	Per path segment	Maps endpoints for a specific segment (e.g., app.MapAccountsEndpoints())
app.MapHealthCheckEndpoints()	healthChecks.enabled: true	Maps /health, /health/live, /health/ready with optional API key security
app.Map{Project}Webhooks()	Webhooks in spec	Maps webhook receiver endpoints

Endpoint Definition Pattern

When using EndpointPerOperation mode, each operation gets its own class:

// Generated per operation
public sealed class GetAccountByIdEndpoint : IEndpointDefinition
{
    internal const string ApiRouteBase = "/accounts";

    public void DefineEndpoints(WebApplication app) { ... }
}

---

📋 Generated Types

Models (Records)

Generated from OpenAPI components/schemas:

[GeneratedCode("Atc.Rest.Api.SourceGenerator", "1.0.0")]
public sealed record Account(
    Guid Id,
    string Name,
    string? Description,
    DateTimeOffset CreatedAt);

• sealed record by default (use generatePartialModels: true for partial record)
• Optional properties are nullable with ?
• readOnly / writeOnly properties are nullable with null default
• [Required], [StringLength], [Range] validation attributes from OpenAPI constraints
• /// <summary> from schema description, /// <example> from schema example

Parameters

Generated from operation parameters and request body:

[GeneratedCode("Atc.Rest.Api.SourceGenerator", "1.0.0")]
public sealed record GetAccountByIdParameters(
    [property: FromRoute(Name = "accountId"), Required] Guid AccountId);

public sealed record CreateAccountParameters(
    [property: FromBody, Required] Account Body);

Result Types

Generated from operation responses:

[GeneratedCode("Atc.Rest.Api.SourceGenerator", "1.0.0")]
public class GetAccountByIdResult : IResult
{
    public static GetAccountByIdResult Ok(Account response) => ...
    public static GetAccountByIdResult NotFound() => ...

    public static IResult ToIResult(GetAccountByIdResult result) => ...
}

Handler Interfaces

Generated from operations — implemented by the developer:

public interface IGetAccountByIdHandler
{
    Task<GetAccountByIdResult> ExecuteAsync(
        GetAccountByIdParameters parameters,
        CancellationToken cancellationToken);
}

Client Types

Generated by the client generator, in addition to the models and parameters above:

Type	Mode	Shape
{ClientName}	TypedClient	sealed class, implements I{ClientName}
I{ClientName}	TypedClient	Interface declaring every operation — always generated, no opt-in flag
Add{ClientName}()	TypedClient	DI extension, emitted when Microsoft.Extensions.Http is referenced
{Operation}Endpoint	EndpointPerOperation	sealed class, implements I{Operation}Endpoint
{Operation}EndpointResult	EndpointPerOperation	partial class with a static factory per documented response

// Always partial — extend it from your own file, no marker-file flag needed.
public partial class GetAccountByIdEndpointResult : EndpointResponse, IGetAccountByIdEndpointResult
{
    public static GetAccountByIdEndpointResult Ok(Account content) => ...
    public static GetAccountByIdEndpointResult NotFound() => ...
}

ℹ️ generatePartialModels applies to models only. Endpoint result classes are partial unconditionally; the typed client class stays sealed — depend on I{ClientName} instead of deriving from it.

➡️ See Working with C# Client Testing for how these are used in tests.

---

📊 Policy Constants

Rate Limiting

// Generated from x-ratelimit-* extensions
public static class RateLimitPolicies
{
    public const string Global = "global";
    public const string AccountsStrict = "accounts-strict";
}

Resilience

// Generated from x-retry-* extensions
public static class ResiliencePolicies
{
    public const string Standard = "standard";
    public const string ExternalService = "external-service";
}

Security

// Generated from security schemes
public static class SecurityPolicies
{
    public const string BearerAuth = "BearerAuth";
    public const string ReadAccounts = "read:accounts";
}

Caching

// Generated from x-cache-* extensions
public static class OutputCachePolicies
{
    public const string AccountsList = "accounts-list";
}

public static class CachePolicies
{
    public const string AccountsDetail = "accounts-detail";
}

---

🔑 Constants

// Generated for EndpointPerOperation mode
public static class Constants
{
    public const string HttpClientName = "MyApi-ApiClient";
}

Usage in DI:

services.AddHttpClient(Constants.HttpClientName, client =>
{
    client.BaseAddress = new Uri("https://api.example.com");
});

---

🔗 Related Guides

• Marker Files — Configuration options that control what gets generated
• Working with Configuration — ApiGeneratorOptions.json reference
• Working with Security — Security scheme generation details
• Working with Rate Limiting — Rate limit policy generation
• Working with Resilience — Resilience policy generation
• Working with Caching — Cache policy generation
• Development Notes — Extractor architecture