Atc.Rest.Api.SourceGenerator 1.0.272

🚀 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

📦 Quick Setup

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 Files

For a typical three-layer architecture, use different marker files per project:

Contracts project - .atc-rest-api-server:

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

Domain project - .atc-rest-api-server-handlers:

{
  "generate": true,
  "generateHandlersOutput": "Handlers"
}

💡 See Marker Files Reference for all configuration options.

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()

5. Implement Handlers

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!

6. Wire Up Program.cs

var builder = WebApplication.CreateBuilder(args);

builder.Services.AddOpenApi();
builder.Services.AddApiHandlersFromDomain();

var app = builder.Build();

app.MapOpenApi();
app.MapApiEndpoints();

app.Run();

📋 Requirements

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

Optional Dependencies

For EndpointPerOperation client generation mode:

<PackageReference Include="Atc" Version="3.*" />
<PackageReference Include="Atc.Rest.Client" Version="2.*" />

🏗️ Architecture

The project uses a three-layer architecture:

Benefits: Testability, reusability across CLI and source generators, clear separation of concerns.

🖥️ CLI Tool

Installation Guide

The atc-rest-api-gen CLI provides a guided experience for project setup and validation:

# Generate server project (contracts + domain)
atc-rest-api-gen generate server -s api.yaml -o output/MyApp.Api.Contracts -n MyApp.Api.Contracts

# Generate client project
atc-rest-api-gen generate client -s api.yaml -o output/MyApp.Client -n MyApp.Client

# Generate TypeScript client (fetch or Axios, with optional hooks/Zod/scaffold)
atc-rest-api-gen generate client-typescript -s api.yaml -o ./src/api --hooks ReactQuery

# Validate OpenAPI specification
atc-rest-api-gen spec validate -s api.yaml

# Create default configuration file
atc-rest-api-gen options create -o ./

See Working with the CLI for full documentation.

📚 WIKI - Documentation

Read the full documentation on the WIKI

🎯 Generated from This YAML

paths:
  /pets:
    get:
      operationId: listPets
      parameters:
        - name: limit
          in: query
          schema:
            type: integer
            maximum: 100
      responses:
        '200':
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Pet'

⬇️ To This C# Code

// Generated model
public record Pet(
    [property: Required] long Id,
    [property: Required] string Name,
    string? Tag);

// Generated parameters
public class ListPetsParameters
{
    [FromQuery(Name = "limit")]
    [Range(long.MinValue, 100)]
    public int? Limit { get; set; }
}

// Generated handler interface
public interface IListPetsHandler
{
    Task<ListPetsResult> ExecuteAsync(
        ListPetsParameters parameters,
        CancellationToken ct = default);
}

// Generated result - ONLY factory methods for responses in OpenAPI!
public class ListPetsResult : IResult
{
    private ListPetsResult(IResult inner) { ... }  // Private!

    public static ListPetsResult Ok(Pet[] response) => ...
    public static implicit operator ListPetsResult(Pet[] r) => Ok(r);
    // No InternalServerError(), Unauthorized(), etc. - they don't exist!
}

// Generated endpoint
endpoints.MapGet("/pets", async (
    [FromServices] IListPetsHandler handler,
    [AsParameters] ListPetsParameters parameters,
    CancellationToken ct)
    => await handler.ExecuteAsync(parameters, ct));

🏷️ Marker Files