Development Notes

🛠️ Development Notes

This guide is for developers contributing to the Atc.Rest.Api.SourceGenerator project. It covers the architecture, testing setup, and common development tasks.

🏗️ Project Architecture

📐 Three-Layer Architecture

The project uses a three-layer architecture that separates shared logic from Roslyn-specific code and CLI:

+------------------------------------------------------------+
|               🔮 Atc.Rest.Api.SourceGenerator              |
|           (Roslyn Source Generators - netstandard2.0)      |
|  +-------------------+  +-------------------+  +---------+ |
|  |ApiServerGenerator|  |ApiClientGenerator|  |ApiDomain| |
|  +--------+----------+  +---------+---------+  +----+----+ |
|           |                       |                 |      |
|           +-----------------------+-----------------+      |
|                                   v                        |
|  +----------------------------------------------------------+ |
|  |     🔧 Helpers (DiagnosticHelpers - Roslyn-specific)     | |
|  |     🔍 Extractors (RoslynSchemaExtractor - assembly scan)| |
|  +----------------------------------------------------------+ |
+-----------------------------+--------------------------------+
                              | depends on
                              v
+------------------------------------------------------------+
|                   📦 Atc.Rest.Api.Generator                |
|              (Shared Library - netstandard2.0)             |
|  +--------------------------------------------------------+ |
|  |      🔧 Extractors (ALL 12 - OpenAPI -> Parameters)    | |
|  |  SchemaExtractor, EnumExtractor, HandlerExtractor,     | |
|  |  ResultClassExtractor, EndpointDefinitionExtractor,    | |
|  |  HttpClientExtractor, EndpointPerOperationExtractor... | |
|  +--------------------------------------------------------+ |
|  +--------------------------------------------------------+ |
|  |           ⚙️ Services (CodeGenerationService)          | |
|  +--------------------------------------------------------+ |
|  +---------------+  +--------------+  +------------------+  |
|  |⚙️Configurations|  | ✅Validators |  |    📋 Models    |  |
|  +---------------+  +--------------+  +------------------+  |
+------------------------------------------------------------+

✨ Benefits of this architecture:

🧪 Testability: Shared logic tested without Roslyn dependencies
🔄 Reusability: Generator library powers both Source Generator AND CLI tool
🛠️ Maintainability: Clear separation of concerns
⚡ Build performance: Smaller source generator assembly

📁 Solution Structure

atc-rest-api-source-generator/
├── 📁 src/
│   ├── 📦 Atc.NetStandard20/                      # Core utilities
│   ├── 📦 Atc.CodeGeneration.CSharp/              # Code gen library
│   ├── 📦 Atc.OpenApi/                            # OpenAPI extensions
│   ├── 📦 Atc.Rest.Api.Generator/                 # Shared library (ALL business logic)
│   │   ├── 📁 Abstractions/                       # ICodeGenerator, IDiagnosticReporter
│   │   ├── 📁 Configurations/                     # ServerConfig, ClientConfig, etc.
│   │   ├── 📁 Extractors/                         # ALL 12 extractors
│   │   ├── 📁 Services/                           # CodeGenerationService
│   │   ├── 📁 Validators/                         # CasingHelper, OpenApiDocumentValidator
│   │   └── 📁 Helpers/                            # PathSegmentHelper, RuleIdentifiers
│   ├── 🔮 Atc.Rest.Api.SourceGenerator/           # Roslyn generators (thin wrappers)
│   └── 💻 Atc.Rest.Api.CliGenerator/              # CLI tool (net10.0)
├── 📁 sample/
│   └── 📁 Minimal/
│       ├── 🐕 PetStoreSimple/                     # Basic 3-endpoint example
│       ├── 🐕 PetStoreFull/                       # Extended example
│       └── 🎪 Showcase/                           # Full-featured demo
└── 📁 test/
    ├── 🧪 Atc.Rest.Api.Generator.Tests/           # Shared library unit tests
    ├── 🧪 Atc.Rest.Api.Generator.IntegrationTests/# Generator integration tests
    ├── 🧪 Atc.Rest.Api.SourceGenerator.Tests/     # SourceGenerator tests
    └── 🧪 Atc.Rest.Api.CliGenerator.Tests/        # CLI command tests

🔄 Generator Architecture

The generators follow the Extractor Pattern:

📄 OpenAPI Document -> 🔧 Extractors -> 📋 Parameter Records -> ⚙️ Code Generators -> 💻 C# Code

🔧 Extractors (All in Atc.Rest.Api.Generator)

Extractor	Input	Output
`SchemaExtractor`	OpenAPI schemas	`RecordsParameters`
`EnumExtractor`	OpenAPI string enums	`EnumParameters`
`HandlerExtractor`	OpenAPI operations	`InterfaceParameters`
`OperationParameterExtractor`	Operation params	`ClassParameters`
`ResultClassExtractor`	Operation responses	Result class code
`EndpointDefinitionExtractor`	Operations	`EndpointDefinitionParameters`
`HandlerScaffoldExtractor`	Operations	Handler stub code
`HttpClientExtractor`	Operations	TypedClient code
`EndpointPerOperationExtractor`	Operations	Per-operation endpoint classes

💡 Note: Only RoslynSchemaExtractor remains in SourceGenerator (requires Roslyn for assembly scanning).

🧪 Testing

📁 Test Project Structure

test/
├── 🧪 Atc.Rest.Api.Generator.Tests/        # Shared library unit tests (198 tests)
├── 🧪 Atc.Rest.Api.Generator.IntegrationTests/ # Generator integration tests (52 tests)
├── 🧪 Atc.Rest.Api.SourceGenerator.Tests/  # SourceGenerator tests (242 tests)
├── 🧪 Atc.Rest.Api.CliGenerator.Tests/     # CLI command tests (16 tests)
└── 📁 Scenarios/                           # Shared test scenarios
    ├── 🎪 Demo/                            # Comprehensive demo scenario
    ├── 🐕 PetStoreSimple/                  # Minimal 3-endpoint API
    ├── 🚦 RateLimit/                       # x-ratelimit-* extensions
    ├── 🔄 Retry/                           # x-retry-* resilience extensions
    ├── 🔐 Security*/                       # Security scheme variations
    └── 🔢 Versioning*/                     # API versioning strategies

▶️ Running Tests

# 🧪 Run all tests
dotnet test

# 🎯 Run specific test category
dotnet test --filter "FullyQualifiedName~GeneratorComparisonTests"

# 📋 Run tests for specific scenario
dotnet test --filter "DisplayName~PetStoreSimple"

# ✅ Run validation tests only
dotnet test --filter "FullyQualifiedName~ValidationTests"

# 📝 Run with verbose output
dotnet test -v detailed

📸 Snapshot Testing with Verify

We use Verify for snapshot testing generated code.

🔄 How It Works

🧪 Tests generate code using the source generators
📊 Output is compared against .verified.cs baseline files
❌ Differences are shown in .received.cs files
👀 Developer reviews and accepts/rejects changes

👀 Review Changes

When tests fail due to generated code changes:

# 📋 Review all pending changes
dotnet verify review

# ✅ Accept all changes (update baselines)
dotnet verify accept

# 📄 Accept specific file
dotnet verify accept --file "path/to/test.cs"

➕ Adding a New Scenario

📁 Create folder in test/Scenarios/{ScenarioName}/
📄 Add OpenAPI spec: {ScenarioName}.yaml

⚙️ Add marker files:

.atc-rest-api-server-contracts
.atc-rest-api-client-contracts
.atc-rest-api-server-handlers

▶️ Run tests to generate .received.cs files
✅ Review and accept:
```
dotnet verify accept
```
💾 Commit .verified.cs files to source control

🔨 Build Commands

🏗️ Build the Solution

# 🐛 Debug build
dotnet build

# 📦 Release build (warnings as errors)
dotnet build -c Release

▶️ Run Sample Projects

# 🐕 PetStoreSimple
dotnet run --project sample/PetStoreSimple/PetStoreSimple.Api/PetStoreSimple.Api.csproj

# 🐕 PetStoreSimple with Aspire
dotnet run --project sample/PetStoreSimple/PetStoreSimple.Aspire/PetStoreSimple.Aspire.csproj

# 🎪 Showcase with Aspire
dotnet run --project sample/Showcase/Showcase.Aspire/Showcase.Aspire.csproj

🧹 Clean Build

dotnet clean
rm -rf **/obj **/bin
dotnet build

🐛 Debugging Tips

👁️ See Generated Files

Add to .csproj:

<PropertyGroup>
  <EmitCompilerGeneratedFiles>true</EmitCompilerGeneratedFiles>
</PropertyGroup>

Generated files appear in:

obj/Generated/Atc.Rest.Api.SourceGenerator/
├── 📁 ApiServerGenerator/
│   └── *.g.cs
├── 📁 ApiClientGenerator/
│   └── *.g.cs
└── 📁 ApiServerDomainGenerator/
    └── *.cs (physical files)

🔍 Debug Source Generator

🛑 Add Debugger.Launch() in generator:

public void Initialize(IncrementalGeneratorInitializationContext context)
{
    #if DEBUG
    if (!Debugger.IsAttached)
    {
        Debugger.Launch();
    }
    #endif
    // ...
}

🏗️ Build a project that uses the generator
🔗 Visual Studio will prompt to attach debugger

📋 Diagnostic Rules Reference

For a complete reference of all diagnostic rules, see Analyzer Rules.

❌ Common Errors

Rule ID	Description	Solution
ATC_API_DEP001	Server requires ASP.NET Core	Add `<FrameworkReference Include="Microsoft.AspNetCore.App" />`
ATC_API_DEP003	EndpointPerOperation requires Atc.Rest.Client	Install `Atc.Rest.Client` NuGet package
ATC_API_DEP007	useMinimalApiPackage requires package	Install `Atc.Rest.MinimalApi` or set to `"disabled"`
ATC_API_OPR001	Missing operationId	Add `operationId` to each operation in OpenAPI spec
ATC_API_VAL002	OpenAPI 2.0 not supported	Upgrade to OpenAPI 3.0.x specification

📦 Dependencies

🔮 Source Generator Dependencies

<PackageReference Include="Microsoft.OpenApi.YamlReader" Version="3.0.1" />
<PackageReference Include="Microsoft.OpenApi" Version="3.0.1" />
<PackageReference Include="SharpYaml" Version="2.1.4" />
<PackageReference Include="Microsoft.CodeAnalysis.CSharp" Version="4.14.0" />
<PackageReference Include="Microsoft.CodeAnalysis.Analyzers" Version="3.11.0" />

🔗 Project References

🔮 Atc.Rest.Api.SourceGenerator
├── 📦 Atc.Rest.Api.Generator           # Shared library
├── 📦 Atc.NetStandard20                # String utilities
├── 📦 Atc.CodeGeneration.CSharp        # Code generation
└── 📦 Atc.OpenApi                      # OpenAPI extensions

⚠️ Important Version Notes

Microsoft.OpenApi v3.0.1: Breaking changes from v1.x
- Uses IOpenApiSchema interface
- Pattern match OpenApiSchemaReference vs OpenApiSchema
- schemaRef.Reference.Id instead of schemaRef.Id
- JsonSchemaType enum instead of string types

📝 Code Style

🔍 Analyzers Enforced

<PackageReference Include="StyleCop.Analyzers" Version="1.2.0-beta.507" />
<PackageReference Include="Meziantou.Analyzer" Version="2.0.256" />
<PackageReference Include="SonarAnalyzer.CSharp" Version="10.15.0.120848" />
<PackageReference Include="AsyncFixer" Version="1.6.0" />
<PackageReference Include="SecurityCodeScan.VS2019" Version="5.6.7" />

📋 Key Conventions

✅ Use #nullable enable in all generated code
📝 Use records for models, classes for services
➡️ Prefer expression-bodied members
📖 XML documentation on public APIs
🔤 camelCase for private fields (no underscore prefix)

🤝 Contributing Workflow

🍴 Fork the repository
🌿 Create a branch for your feature
💻 Implement following existing patterns
🧪 Add tests (validation tests, scenario tests)
🏗️ Run dotnet build -c Release (must pass with 0 warnings)
✅ Run dotnet test (must pass)
🚀 Submit PR with description of changes

🔗 Quick Links

Resource	Path
📦 Shared Library	`src/Atc.Rest.Api.Generator/`
🔮 Source Generators	`src/Atc.Rest.Api.SourceGenerator/`
🔧 Extractors (ALL 12)	`src/Atc.Rest.Api.Generator/Extractors/`
⚙️ Services	`src/Atc.Rest.Api.Generator/Services/`
✅ Validators	`src/Atc.Rest.Api.Generator/Validators/`
⚙️ Configurations	`src/Atc.Rest.Api.Generator/Configurations/`
📄 OpenAPI Extensions	`src/Atc.OpenApi/Extensions/`
🧪 Test Scenarios	`test/Scenarios/`
📋 Samples	`sample/`

Development Notes

🛠️ Development Notes

🏗️ Project Architecture

📐 Three-Layer Architecture

📁 Solution Structure

🔄 Generator Architecture

🔧 Extractors (All in Atc.Rest.Api.Generator)

🧪 Testing

📁 Test Project Structure

▶️ Running Tests

📸 Snapshot Testing with Verify

🔄 How It Works

👀 Review Changes

➕ Adding a New Scenario

🔨 Build Commands

🏗️ Build the Solution

▶️ Run Sample Projects

🧹 Clean Build

🐛 Debugging Tips

👁️ See Generated Files

🔍 Debug Source Generator

📋 Diagnostic Rules Reference

❌ Common Errors

📦 Dependencies

🔮 Source Generator Dependencies

🔗 Project References

⚠️ Important Version Notes

📝 Code Style

🔍 Analyzers Enforced

📋 Key Conventions

🤝 Contributing Workflow

🔗 Quick Links

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

🏠 Home

📖 Getting Started

⚙️ Features

📋 Reference

🔗 Resources

Clone this wiki locally