Roadmap

🗺️ Roadmap

This document provides a comprehensive view of feature status, planned features, and strategic direction for the Atc.Rest.Api.SourceGenerator project.

---

🎯 Project Vision

To provide a production-ready, enterprise-grade Roslyn source generator that automatically generates high-quality REST API server and client code from OpenAPI specifications, with full Native AOT support and minimal runtime overhead.

🌟 Core Principles:

1. ⚡ Zero-configuration - Works out of the box with sensible defaults
2. 🔒 Contract-enforced results - Handlers can only return responses defined in OpenAPI
3. 🛡️ Type safety - Compile-time validation of API contracts
4. 🚀 Minimal API - Modern ASP.NET Core patterns (not MVC Controllers)
5. 📦 Native AOT - Full compatibility with ahead-of-time compilation

---

📊 Feature Status Overview

🖥️ Server Features

Feature	Status
Record type generation	✅ Done
Nullable reference types	✅ Done
Property validation attributes	✅ Done
Array/collection handling	✅ Done
Nested object support	✅ Done
allOf composition (generic types)	✅ Done
Type conflict resolution	✅ Done
Enum generation	✅ Done
oneOf/anyOf polymorphism	✅ Done
AdditionalProperties (Dictionary)	✅ Done
Query/Path parameter DTOs	✅ Done
Handler interfaces per operation	✅ Done
MapGet/MapPost/MapPut/MapDelete	✅ Done
[AsParameters] binding	✅ Done
Endpoint grouping (MapGroup)	✅ Done
IEndpointDefinition pattern	✅ Done
ValidationFilter integration	✅ Done
GlobalErrorHandlingMiddleware	✅ Done
API versioning support	✅ Done
File upload (IFormFile)	✅ Done
multipart/form-data	✅ Done
Handler scaffolding with assembly scanning	✅ Done

🔐 Security & Authorization

Feature	Status
x-authentication-* extensions (ATC)	✅ Done
x-authorize-roles extension	✅ Done
.RequireAuthorization() generation	✅ Done
[AllowAnonymous] override	✅ Done
SecurityPolicies constants	✅ Done
OAuth2 scopes policy generation	✅ Done
Bearer/JWT scheme	✅ Done
API Key scheme	✅ Done
OpenID Connect scheme	✅ Done

🚦 Rate Limiting

Feature	Status
x-ratelimit-* extensions	✅ Done
Document/Path/Operation-level policies	✅ Done
.RequireRateLimiting() generation	✅ Done
RateLimitPolicies constants	✅ Done
Fixed/Sliding/TokenBucket limiters	✅ Done
AddApiRateLimiting() DI extension	✅ Done

🗄️ Caching

Feature	Status
📤 Output Caching (x-cache-type: output)	✅ Done
OutputCachePolicies constants	✅ Done
AddApiOutputCaching() DI extension	✅ Done
.CacheOutput() endpoint integration	✅ Done
🔀 HybridCache (x-cache-type: hybrid)	✅ Done
CachePolicies constants	✅ Done
AddApiCaching() DI extension	✅ Done
In-Memory/Distributed/Hybrid modes	✅ Done
Tag-based invalidation	✅ Done

📱 Client Features

Feature	Status
TypedClient HTTP client	✅ Done
GET/POST/PUT/DELETE methods	✅ Done
IAsyncEnumerable streaming	✅ Done
File upload (Stream)	✅ Done
PaginatedResult support	✅ Done
EndpointPerOperation mode	✅ Done
BinaryEndpointResponse for downloads	✅ Done
OAuth token management	✅ Done

🔄 Resilience & Retry

Feature	Status
x-retry-* extensions	✅ Done
ResiliencePolicies constants	✅ Done
AddApiResilience() DI extension	✅ Done
Exponential backoff retry	✅ Done
Circuit breaker support	✅ Done
Configurable CB parameters	✅ Done
Timeout configuration	✅ Done
Retry-After header handling	✅ Done

✅ Validation

Feature	Status
None / Standard / Strict strategies	✅ Done
Core validation rules (VAL001-002)	✅ Done
Naming rules (NAM001-006)	✅ Done
Schema rules (SCH001-013)	✅ Done
Operation rules (OPR001-025)	✅ Done
Security rules (SEC001-010)	✅ Done

📋 Total: 66 validation rules implemented across 9 categories

---

📜 OpenAPI Version Support

Version	Status
OpenAPI 3.0.x (3.0.0-3.0.4)	✅ Supported
OpenAPI 3.1.x	⚠️ Partial support
OpenAPI 2.0 (Swagger)	🚫 Blocked (VAL002 error)

⚠️ OpenAPI 3.1 specific features not yet supported:

• Nullable type arrays (type: [string, null])
• $ref with sibling properties
• Webhooks
• JSON Schema 2020-12

---

🔮 Not Yet Implemented

🖥️ Server Generation

Feature	Priority	Notes
MVC Controller generation	💭 Nice-to-have	Only Minimal API supported

📄 Model Generation

Feature	Priority	Notes
Recursive schemas	💭 Nice-to-have	Tree structures
not schemas	🔽 Low	Negation patterns

📱 Client Generation

Feature	Priority	Notes
Request/response logging	💭 Nice-to-have	ILogger integration

---

🚀 Future Enhancements

📝 Custom Templates

Allow developers to customize generated code structure:

{
  "templatePath": "Templates/CustomHandler.template"
}

🏗️ Repository Pattern Generation

Auto-generate repository interfaces alongside handlers:

public interface IPetRepository
{
    Task<Pet?> GetByIdAsync(long id, CancellationToken ct);
    Task<Pet[]> ListAsync(int? limit, CancellationToken ct);
}

🧪 Unit Test Stub Generation

Generate xUnit test stubs for handlers:

public class ListPetsHandlerTests
{
    [Fact]
    public async Task ExecuteAsync_ReturnsOk_WhenPetsExist()
    {
        // Arrange, Act, Assert
    }
}

🔌 Plugin System

Extensible validation and generation:

public interface IGeneratorPlugin
{
    void OnSchemaProcessed(OpenApiSchema schema, StringBuilder output);
    void OnOperationProcessed(OpenApiOperation operation, StringBuilder output);
}

---

📈 Implementation Statistics

Category	Implemented	Percentage
🖥️ Server features	60/60	100%
📱 Client features	26/26	100%
✅ Validation rules	66/66	100%
🗄️ Caching features	20/20	100%
📜 OpenAPI 3.0 support	~95%	~95%
📜 OpenAPI 3.1 support	~70%	~70%

---

⚠️ Breaking Changes from CLI Tool

If migrating from atc-rest-api-generator CLI:

Change	🔴 Old	🟢 New
Models	Classes	Records
Parameters	Individual args	Parameters class
Request body	Separate parameter	parameters.Request
Endpoints	MVC Controllers	Minimal API
Generation	CLI command	On build
Configuration	ApiGeneratorOptions.json	Marker files

---

📅 Version History

🏷️ Current: Preview

• ✅ Server Minimal API generation
• ✅ Client TypedClient + EndpointPerOperation modes
• ✅ Handler scaffolding
• ✅ Enum generation
• ✅ File upload/download support
• ✅ IAsyncEnumerable streaming
• ✅ Pagination with allOf
• ✅ All 66 validation rules implemented
• ✅ Rate Limiting
• ✅ Resilience & Retry
• ✅ Security Enhancements
• ✅ OAuth Token Management
• ✅ API Versioning
• ✅ Server-Side Caching (Output Caching + HybridCache)

🏷️ Planned: v1.0

• 📋 Full OpenAPI 3.1 support
• 📋 Documentation generation
• 📋 Performance benchmarks

🏷️ Future: v2.0+

• 💭 MVC Controller support (maybe)
• 💭 Custom templates
• 💭 Unit test generation
• 💭 Repository pattern
• 💭 Plugin system

---

🤝 Contributing

Want to help implement a feature?

🌱 Good First Issues

• Add array URL encoding support in TypedClient mode
• Implement OpenAPI 3.1 nullable type arrays
• Add request/response logging support

📝 How to Contribute

1. 🔍 Check existing issues on GitHub
2. 📝 Create an issue describing the feature
3. 🍴 Fork the repository
4. 💻 Implement following existing patterns
5. 🧪 Add tests using the scenario testing framework
6. 🚀 Submit a PR