Home

🏠 Atc.Rest.Api.SourceGenerator

A Roslyn Source Generator that automatically generates REST API server and client code from OpenAPI specifications. No CLI commands, no manual code generation - just build your project and get production-ready code.

✨ Key Features

Area	Feature	Description
Core	🔧 Zero Configuration	Add the NuGet package, drop your YAML file, build
	🏗️ Minimal API	Generates modern ASP.NET Core minimal API endpoints
	🔒 Contract-Enforced Results	Handlers can only return responses defined in OpenAPI - compile-time safety!
	✅ Validation	Automatic [Required], [Range], [StringLength] from OpenAPI constraints
Server	📝 Handler Scaffolds	Auto-generates handler stubs for unimplemented operations
	🔐 Security	JWT, OAuth2 scopes, API Key, role-based auth - all from OpenAPI
	⏱️ Rate Limiting	Server-side rate limiting from x-ratelimit-* extensions
	💾 Caching	Output caching and HybridCache support from x-cache-* extensions
Client	🔌 Type-Safe Client	Strongly-typed HTTP client with full IntelliSense
	🔄 Resilience	Client-side retry/circuit breaker from x-retry-* extensions
	🔗 URL Encoding	Automatic RFC 3986 compliant encoding - no more broken URLs
Models	🎯 Enum Support	Generates C# enums from OpenAPI string enums
	📊 Pagination	Generic PaginatedResult<T> from allOf composition
Data	📁 File Uploads	Full support for binary uploads (single, multiple, with metadata)
	🌊 Streaming	IAsyncEnumerable<T> support for efficient data streaming
CLI	🖥️ Project Scaffolding	generate server / generate client creates complete project structure
	🟦 TypeScript Client	generate client-typescript — Fetch/Axios, interceptors, retry, MSW handlers
	⚛️ React Hooks	React Query (useQuery/useMutation/useInfiniteQuery/useSuspenseQuery) + SWR — streaming hooks for IAsyncEnumerable
	🪪 Branded ID types	--branded-ids emits nominal types — getUser(petId) becomes a compile error
	🔍 Runtime Zod validation	--zod-runtime-validate wires Zod into response parsing — spec-drift detection
	🔌 SignalR Hub Hooks	x-signalr-hubs extension → typed use<Hub>Hub() with auto-reconnect
	📋 Spec Validation	spec validate validates OpenAPI specs with strict/standard modes
	🔗 Multi-Part Specs	spec merge / spec split for large API specifications
	⚙️ Options Management	options create / options validate for configuration files
	🔄 Migration	migrate validate / migrate execute to migrate from old CLI generator

⚡ Quick Start

1️⃣ Install the Package

dotnet add package Atc.Rest.Api.SourceGenerator

2️⃣ Add Your OpenAPI Spec

Add your *.yaml file and marker file to .csproj:

<ItemGroup>
  <AdditionalFiles Include="MyApi.yaml" />
  <AdditionalFiles Include=".atc-rest-api-server" />
</ItemGroup>

3️⃣ Create Marker File

Create .atc-rest-api-server:

{
  "generate": true,
  "validateSpecificationStrategy": "Standard"
}

4️⃣ Build and Use

dotnet build

Generated code includes:

• 📦 Models - C# records with validation attributes
• 🎯 Handler Interfaces - IListPetsHandler, ICreatePetHandler, etc.
• 🛣️ Endpoints - Minimal API MapGet, MapPost, etc.
• 💉 DI Extensions - AddApiHandlersFromDomain(), MapApiEndpoints()

💡 Tip: Use the CLI tool to scaffold complete projects automatically!

dotnet tool install -g atc-rest-api-gen
atc-rest-api-gen generate server -s api.yaml -o ./my-api -n MyApi

See Getting Started with CLI for a complete walkthrough.

🔄 Migrating from the old CLI generator? Use the built-in migration tool:

atc-rest-api-gen migrate validate -s ./my-project -p api.yaml
atc-rest-api-gen migrate execute -s ./my-project -p api.yaml

See Migration Guide for step-by-step instructions.

📋 Requirements

• .NET 10 or later
• OpenAPI 3.0.x or 3.1.x specification

🏗️ Architecture

The project uses a three-layer architecture:

Layer	Project	Description
📦 Shared	Atc.Rest.Api.Generator	All extractors, services, configuration, validation (Roslyn-independent)
⚙️ Generators	Atc.Rest.Api.SourceGenerator	Roslyn source generators (thin wrappers calling shared services)
🛠️ CLI	Atc.Rest.Api.Generator.Cli	Command-line tool for validation and generation

💡 Example: Type-Safe Results

public class GetPetByIdHandler : IGetPetByIdHandler
{
    public async Task<GetPetByIdResult> ExecuteAsync(
        GetPetByIdParameters parameters,
        CancellationToken ct)
    {
        var pet = await repository.GetByIdAsync(parameters.PetId, ct);

        // ✅ Clean syntax with implicit operator
        if (pet is not null)
            return pet;  // Implicitly converts to GetPetByIdResult.Ok(pet)

        // ✅ Factory methods for error responses
        return GetPetByIdResult.NotFound();

        // ❌ COMPILE ERROR - Method doesn't exist!
        // return GetPetByIdResult.InternalServerError();
    }
}

🔒 Type-Safe Results: Result classes have private constructors and factory methods matching your OpenAPI responses. You literally cannot return a status code that isn't in your spec!

🏷️ Marker Files

File	Purpose
.atc-rest-api-server	Server code (models, endpoints, handlers)
.atc-rest-api-server-handlers	Handler implementation scaffolds
.atc-rest-api-client	HTTP client generation

📜 License

MIT License - see LICENSE for details.