rest-api-generator

name	rest-api-generator
description	ATC REST API source generator and CLI for producing server endpoints, C# clients, and TypeScript clients from OpenAPI specifications. Use when the user asks to generate a REST API from an OpenAPI spec, scaffold server handlers, create typed HTTP clients, generate TypeScript clients with React Query hooks, configure API security or rate limiting, set up caching or resilience, version an API, generate webhooks, merge multi-part OpenAPI specs, or migrate from the old atc-rest-api-generator CLI. Use when this capability is needed.
metadata	{"author":"atc-net"}

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

---

Source: atc-net/atc-agentic-toolkit — distributed by TomeVault.