ATC REST API Source Generator

A Roslyn Source Generator and CLI tool that automatically generates production-ready REST API server and client code from OpenAPI specifications. Zero CLI commands for server generation — install the NuGet package, add your YAML spec, create marker files, and build.

Key differentiator: Compile-time code generation with type-safe results, contract-enforced handlers, and full OpenAPI 3.x support including security, rate limiting, caching, resilience, and versioning — all configured via OpenAPI extensions.

Detailed reference material lives in the references/ folder — load on demand.

---

References

Reference	When to load
Marker Files	Configuring .atc-rest-api-server, .atc-rest-api-server-handlers, .atc-rest-api-client
CLI Reference	CLI commands, TypeScript generation, migration, options management
Server Generation	OpenAPI patterns, server endpoints, handlers, type-safe results
Client Generation	C# TypedClient, EndpointPerOperation, TypeScript with fetch/Axios/React Query/Zod
Security	JWT, OAuth2, API Key, OpenID Connect, role-based authorization
Rate Limiting & Caching	Rate limiting algorithms, Output Caching, HybridCache, cache invalidation
Resilience & Versioning	Retry, circuit breaker, timeout, API versioning strategies
Validation & Analyzer Rules	DataAnnotations, FluentValidation, analyzer rule reference

---

1. Quick Start — Source Generator (Server)

Step 1: Install the NuGet package

<PackageReference Include="Atc.Rest.Api.SourceGenerator" Version="*" />

Step 2: Add the OpenAPI spec

Place the YAML/JSON file (e.g. PetStore.yaml) in the project root or a subfolder.

Step 3: Create marker files

Create one or more JSON marker files in the project root to control generation:

.atc-rest-api-server — Server contracts (models, endpoints, type-safe results):

{
  "generate": true,
  "validateSpecificationStrategy": "Strict",
  "useServersBasePath": true,
  "useMinimalApiPackage": "Auto",
  "useValidationFilter": "Auto",
  "useGlobalErrorHandler": "Auto"
}

.atc-rest-api-server-handlers — Handler scaffolds:

{
  "generate": true,
  "validateSpecificationStrategy": "Strict",
  "stubImplementation": "throw-not-implemented"
}

.atc-rest-api-client — C# client contracts:

{
  "generate": true,
  "validateSpecificationStrategy": "Strict",
  "generationMode": "TypedClient",
  "generateOAuthTokenManagement": true
}

Step 4: Build

dotnet build

Generated code appears in obj/ as source-generated files. No manual steps needed.

Step 5: Wire up in Program.cs

var builder = WebApplication.CreateBuilder(args);
builder.Services.AddAtcRestApi();       // Register generated endpoints
builder.Services.AddAtcHandlers();      // Register handler implementations
var app = builder.Build();
app.UseAtcRestApi();                    // Map endpoints
app.Run();

See Marker Files for all configuration options.

---

2. Quick Start — CLI Tool

Install globally:

dotnet tool install -g atc-rest-api-gen

Scaffold a server project

atc-rest-api-gen generate server \
  --specificationPath PetStore.yaml \
  --outputPath ./src \
  --projectName MyApi

Project structure options: SingleProject, TwoProjects, ThreeProjects (default).

Generate a C# client

atc-rest-api-gen generate client \
  --specificationPath PetStore.yaml \
  --outputPath ./src/MyApi.Client \
  --projectName MyApi.Client \
  --generationMode TypedClient

Generation modes: TypedClient (single client class) or EndpointPerOperation (one interface per endpoint, uses Atc.Rest.Client).

Generate a TypeScript client

atc-rest-api-gen generate client-typescript \
  --specificationPath PetStore.yaml \
  --outputPath ./src/ts-client \
  --client-type fetch \
  --hooks react-query \
  --zod \
  --scaffold

Client types: fetch (default), axios. Hooks: none, react-query. Add --zod for Zod schema validation.

See CLI Reference for all commands and options.

---

3. Core Concepts

Type-Safe Results

Every generated endpoint returns a discriminated union result type that enforces handling all possible HTTP responses at compile time:

public class GetPetResult : ResultBase
{
    public static GetPetResult Ok(Pet pet) => new(200, pet);
    public static GetPetResult NotFound(string? message = null) => new(404, message);
}

Handlers must return the correct result type — no IActionResult escape hatch.

Three-Layer Architecture

1. Atc.Rest.Api.Generator (netstandard2.0) — Shared extractors, services, configuration
2. Atc.Rest.Api.SourceGenerator (netstandard2.0) — Roslyn IIncrementalGenerator implementations
3. Atc.Rest.Api.Generator.Cli (net10.0) — CLI tool for scaffolding and validation

Marker File System

Marker files are JSON configuration files that control what gets generated:

Marker File	Purpose
.atc-rest-api-server	Server contracts: models, endpoints, results
.atc-rest-api-server-handlers	Handler scaffolds with stub implementations
.atc-rest-api-client	C# client contracts

OpenAPI Extensions

The generator uses custom x- extensions to configure features beyond standard OpenAPI:

Extension Prefix	Feature
x-authorize-roles	Role-based authorization
x-ratelimit-*	Rate limiting configuration
x-cache-*	Caching (Output Cache or HybridCache)
x-retry-*	Resilience (retry, circuit breaker, timeout)
x-return-async-enumerable	IAsyncEnumerable streaming

---

4. Security Configuration

Supports standard OpenAPI security schemes plus ATC extensions:

Scheme	OpenAPI Type	Extension
JWT Bearer	http / bearer	—
OAuth2	oauth2	—
API Key	apiKey	—
OpenID Connect	openIdConnect	—
Role-based	Any	x-authorize-roles: "Admin,User"

Quick example — JWT with role-based auth:

components:
  securitySchemes:
    BearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT

paths:
  /admin/settings:
    get:
      security:
        - BearerAuth: []
      x-authorize-roles: "Admin"

See Security for OAuth2 scopes, token management, and error handling.

---

5. Rate Limiting, Caching & Resilience

All configured via OpenAPI extensions at document, path, or operation level.

Rate Limiting — algorithms: fixed, sliding, token-bucket, concurrency:

x-ratelimit-policy: "standard"
x-ratelimit-permit-limit: 100
x-ratelimit-window-seconds: 60
x-ratelimit-algorithm: sliding

Caching — Output Caching or HybridCache:

x-cache-type: output          # or "hybrid"
x-cache-expiration-seconds: 300
x-cache-tags: ["pets"]
x-cache-vary-by-query: ["status"]

Resilience — retry, circuit breaker, timeout (Polly v8):

x-retry-max-attempts: 3
x-retry-backoff: exponential
x-retry-use-jitter: true
x-retry-timeout-seconds: 30
x-retry-circuit-breaker: true

See Rate Limiting & Caching and Resilience & Versioning.

---

6. API Versioning

Three strategies configured in the server marker file:

Strategy	URL Example	Marker Setting
QueryString	/pets?api-version=1.0	"versioningStrategy": "QueryString"
UrlSegment	/v1/pets	"versioningStrategy": "UrlSegment"
Header	X-Api-Version: 1.0	"versioningStrategy": "Header"

Requires Asp.Versioning.Http package. See Resilience & Versioning.

---

7. Webhooks & Multi-Part Specs

Webhooks — enable in the server marker file:

{
  "generateWebhooks": true,
  "webhookBasePath": "/webhooks"
}

Multi-Part Specs — merge multiple OpenAPI files:

{
  "multiPartConfiguration": {
    "enabled": true,
    "files": ["pets.yaml", "orders.yaml", "users.yaml"]
  }
}

---

8. Migration from Old CLI

Migrate from the deprecated atc-rest-api-generator:

# Validate first
atc-rest-api-gen migrate validate --projectPath ./src

# Dry run
atc-rest-api-gen migrate execute --projectPath ./src --dry-run

# Execute migration
atc-rest-api-gen migrate execute --projectPath ./src

Changes: project renames, namespace updates, parameter name migration, file restructuring. See CLI Reference for details.

---

9. Validation & Spec Checking

atc-rest-api-gen validate schema --specificationPath PetStore.yaml

Three validation levels: None, Standard, Strict. The generator includes 60+ analyzer rules (ATC_API_* prefix) covering naming, security, schema, and operation validation. See Validation & Analyzer Rules.

---

10. Recommended Packages

Package	Purpose
Atc.Rest.Api.SourceGenerator	Core source generator (required)
Atc.Rest.MinimalApi	Validation filters, global error handler
Atc.Rest.Client	For EndpointPerOperation client mode
Asp.Versioning.Http	API versioning support