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

1. 🧪 Tests generate code using the source generators
2. 📊 Output is compared against .verified.cs baseline files
3. ❌ Differences are shown in .received.cs files
4. 👀 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

1. 📁 Create folder in test/Scenarios/{ScenarioName}/

2. 📄 Add OpenAPI spec: {ScenarioName}.yaml

3. ⚙️ Add marker files:

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

4. ▶️ Run tests to generate .received.cs files

5. ✅ Review and accept:

   dotnet verify accept

6. 💾 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

1. 🛑 Add Debugger.Launch() in generator:

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

2. 🏗️ Build a project that uses the generator

3. 🔗 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

1. 🍴 Fork the repository
2. 🌿 Create a branch for your feature
3. 💻 Implement following existing patterns
4. 🧪 Add tests (validation tests, scenario tests)
5. 🏗️ Run dotnet build -c Release (must pass with 0 warnings)
6. ✅ Run dotnet test (must pass)
7. 🚀 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/