Przejdź do treści
Biblioteka skilli
Programowanie · Budowanie i kod

rest-api-generator

/rest-api-generator

Generuje z OpenAPI serwery, klientów C# i TypeScript z hookami React Query, a także konfiguruje limity, cache, wersje i webhooki.

Licencja
MIT
Ostatnia zmiana repozytorium
27.10.2026

Ocena i bezpieczeństwo

100/ 100Klasa: dobry
Format25 / 25
Frontmatter z nazwą i opisem, poprawna nazwa, opis do 1024 znaków, nazwa zgodna z folderem.
Odkrywalność25 / 25
Opis mówi, kiedy użyć skilla, ma sensowną długość i jest w 3. osobie.
Treść35 / 35
Co najmniej 150 słów i do 500 linii, nagłówki, listy kroków, przykłady albo kod.
Higiena15 / 15
Bez zaślepek typu TODO, bez ścieżek Windows, z licencją.
Ryzykobrak sygnałów w skanie
Pliki w paczce
9
Skrypty
0
Komentarze HTML
0
Adresy URL w SKILL.md
0
Przestarzałość

Brak sygnałów. Repozytorium zmienione 27.10.2026, bez odwołań do wycofanych modeli i API.

Licencja

MIT, otwarta: można używać i zmieniać, z zachowaniem informacji o autorze.

Co robi i kiedy

Generuje z OpenAPI serwery, klientów C# i TypeScript z hookami React Query, a także konfiguruje limity, cache, wersje i webhooki.

Oryginalny opis (EN)

ATC REST API source generator and CLI for producing server endpoints, C# clients, and TypeScript clients from OpenAPI specifications. Use when the user asks to generate a REST API from an OpenAPI spec, scaffold server handlers, create typed HTTP clients, generate TypeScript clients with React Query hooks, configure API security or rate limiting, set up caching or resilience, version an API, generate webhooks, merge multi-part OpenAPI specs, or migrate from the old atc-rest-api-generator CLI.

Jak działa

  1. References
  2. 1. Quick Start — Source Generator (Server)
  3. 2. Quick Start — CLI Tool
  4. 3. Core Concepts
  5. 4. Security Configuration
  6. 5. Rate Limiting, Caching & Resilience
  7. 6. API Versioning
  8. 7. Webhooks & Multi-Part Specs
  9. 8. Migration from Old CLI
  10. 9. Validation & Spec Checking
Sekcje z nagłówków SKILL.md, w oryginale · 330 linii, 1 119 słów
Podgląd SKILL.md
---
name: rest-api-generator
description: 'ATC REST API source generator and CLI for producing server endpoints, C# clients, and TypeScript clients from OpenAPI specifications. Use when the user asks to generate a REST API from an OpenAPI spec, scaffold server handlers, create typed HTTP clients, generate TypeScript clients with React Query hooks, configure API security or rate limiting, set up caching or resilience, version an API, generate webhooks, merge multi-part OpenAPI specs, or migrate from the old atc-rest-api-generator CLI.'
---

# ATC REST API Source Generator

A **Roslyn Source Generator** and CLI tool that automatically generates production-ready REST API server and client code from OpenAPI specifications. Zero CLI commands for server generation — install the NuGet package, add your YAML spec, create marker files, and build.

> **Key differentiator:** Compile-time code generation with type-safe results, contract-enforced handlers, and full OpenAPI 3.x support including security, rate limiting, caching, resilience, and versioning — all configured via OpenAPI extensions.

Detailed reference material lives in the `references/` folder — load on demand.

---

## References

| Reference | When to load |
|---|---|
| [Marker Files](references/marker-files.md) | Configuring `.atc-rest-api-server`, `.atc-rest-api-server-handlers`, `.atc-rest-api-client` |
| [CLI Reference](references/cli-reference.md) | CLI commands, TypeScript generation, migration, options management |
| [Server Generation](references/server-generation.md) | OpenAPI patterns, server endpoints, handlers, type-safe results |
| [Client Generation](references/client-generation.md) | C# TypedClient, EndpointPerOperation, TypeScript with fetch/Axios/React Query/Zod |
| [Security](references/security.md) | JWT, OAuth2, API Key, OpenID Connect, role-based authorization |
| [Rate Limiting & Caching](references/rate-limiting-caching.md) | Rate limiting algorithms, Output Caching, HybridCache, cache invalidation |
| [Resilience & Versioning](references/resilience-versioning.md) | Retry, circuit breaker, timeout, API versioning strategies |
| [Validation & Analyzer Rules](references/validation-rules.md) | DataAnnotations, FluentValidation, analyzer rule reference |

---

## 1. Quick Start — Source Generator (Server)

### Step 1: Install the NuGet package

```xml
<PackageReference Include="Atc.Rest.Api.SourceGenerator" Version="*" />
```

### Step 2: Add the OpenAPI spec

Place the YAML/JSON file (e.g. `PetStore.yaml`) in the project root or a subfolder.

### Step 3: Create marker files

Create one or more JSON marker files in the project root to control generation:

**`.atc-rest-api-server`** — Server contracts (models, endpoints, type-safe results):
```json
{
  "generate": true,
  "validateSpecificationStrategy": "Strict",
  "useServersBasePath": true,
  "useMinimalApiPackage": "Auto",
  "useValidationFilter": "Auto",
  "useGlobalErrorHandler": "Auto"
}
```

**`.atc-rest-api-server-handlers`** — Handler scaffolds:
```json
{
  "generate": true,
  "validateSpecificationStrategy": "Strict",
  "stubImplementation": "throw-not-implemented"
}
```

**`.atc-rest-api-client`** — C# client contracts:
```json
{
  "generate": true,
  "validateSpecificationStrategy": "Strict",
  "generationMode": "TypedClient",
  "generateOAuthTokenManagement": true
}
```

### Step 4: Build

```bash
dotnet build
```

Generated code appears in `obj/` as source-generated files. No manual steps needed.

### Step 5: Wire up in Program.cs

```csharp
var builder = WebApplication.CreateBuilder(args);
builder.Services.AddAtcRestApi();       // Register generated endpoints
builder.Services.AddAtcHandlers();      // Register handler implementations
var app = builder.Build();
app.UseAtcRestApi();                    // Map endpoints
app.Run();
```

See [Marker Files](references/marker-files.md) for all configuration options.

---

## 2. Quick Start — CLI Tool

Install globally:
```bash
dotnet tool install -g atc-rest-api-gen
```

### Scaffold a server project

```bash
atc-rest-api-gen generate server \
  --specificationPath PetStore.yaml \
  --outputPath ./src \
  --projectName MyApi
```

Project structure options: `SingleProject`, `TwoProjects`, `ThreeProjects` (default).

### Generate a C# client

```bash
atc-rest-api-gen generate client \
  --specificationPath PetStore.yaml \
  --outputPath ./src/MyApi.Client \
  --projectName MyApi.Client \
  --generationMode TypedClient
```

Generation modes: `TypedClient` (single client class) or `EndpointPerOperation` (one interface per endpoint, uses `Atc.Rest.Client`).

### Generate a TypeScript client

```bash
atc-rest-api-gen generate client-typescript \
  --specificationPath PetStore.yaml \
  --outputPath ./src/ts-client \
  --client-type fetch \
  --hooks react-query \
  --zod \
  --scaffold
```

Client types: `fetch` (default), `axios`. Hooks: `none`, `react-query`. Add `--zod` for Zod schema validation.

See [CLI Reference](references/cli-reference.md) for all commands and options.

---

## 3. Core Concepts

### Type-Safe Results

Every generated endpoint returns a discriminated union result type that enforces handling all possible HTTP responses at compile time:

```csharp
public class GetPetResult : ResultBase
{
    public static GetPetResult Ok(Pet pet) => new(200, pet);
    public static GetPetResult NotFound(string? message = null) => new(404, message);
}
```

Handlers must return the correct result type — no `IActionResult` escape hatch.

### Three-Layer Architecture

1. **Atc.Rest.Api.Generator** (netstandard2.0) — Shared extractors, services, configuration
2. **Atc.Rest.Api.SourceGenerator** (netstandard2.0) — Roslyn `IIncrementalGenerator` implementations
3. **Atc.Rest.Api.Generator.Cli** (net10.0) — CLI tool for scaffolding and validation

### Marker File System

Marker files are JSON configuration files that control what gets generated:

| Marker File | Purpose |
|---|---|
| `.atc-rest-api-server` | Server contracts: models, endpoints, results |
| `.atc-rest-api-server-handlers` | Handler scaffolds with stub implementations |
| `.atc-rest-api-client` | C# client contracts |

### OpenAPI Extensions

The generator uses custom `x-` extensions to configure features beyond standard OpenAPI:

| Extension Prefix | Feature |
|---|---|
| `x-authorize-roles` | Role-based authorization |
| `x-ratelimit-*` | Rate limiting configuration |
| `x-cache-*` | Caching (Output Cache or HybridCache) |
| `x-retry-*` | Resilience (retry, circuit breaker, timeout) |
| `x-return-async-enumerable` | IAsyncEnumerable streaming |

---

## 4. Security Configuration

Supports standard OpenAPI security schemes plus ATC extensions:

| Scheme | OpenAPI Type | Extension |
|---|---|---|
| JWT Bearer | `http` / `bearer` | — |
| OAuth2 | `oauth2` | — |
| API Key | `apiKey` | — |
| OpenID Connect | `openIdConnect` | — |
| Role-based | Any | `x-authorize-roles: "Admin,User"` |

Quick example — JWT with role-based auth:
```yaml
components:
  securitySchemes:
    BearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT

paths:
  /admin/settings:
    get:
      security:
        - BearerAuth: []
      x-authorize-roles: "Admin"
```

See [Security](references/security.md) for OAuth2 scopes, token management, and error handling.

---

## 5. Rate Limiting, Caching & Resilience

All configured via OpenAPI extensions at document, path, or operation level.

**Rate Limiting** — algorithms: `fixed`, `sliding`, `token-bucket`, `concurrency`:
```yaml
x-ratelimit-policy: "standard"
x-ratelimit-permit-limit: 100
x-ratelimit-window-seconds: 60
x-ratelimit-algorithm: sliding
```

**Caching** — Output Caching or HybridCache:
```yaml
x-cache-type: output          # or "hybrid"
x-cache-expiration-seconds: 300
x-cache-tags: ["pets"]
x-cache-vary-by-query: ["status"]
```

**Resilience** — retry, circuit breaker, timeout (Polly v8):
```yaml
x-retry-max-attempts: 3
x-retry-backoff: exponential
x-retry-use-jitter: true
x-retry-timeout-seconds: 30
x-retry-circuit-breaker: true
```

See [Rate Limiting & Caching](references/rate-limiting-caching.md) and [Resilience & Versioning](references/resilience-versioning.md).

---

## 6. API Versioning

Three strategies configured in the server marker file:

| Strategy | URL Example | Marker Setting |
|---|---|---|
| QueryString | `/pets?api-version=1.0` | `"versioningStrategy": "QueryString"` |
| UrlSegment | `/v1/pets` | `"versioningStrategy": "UrlSegment"` |
| Header | `X-Api-Version: 1.0` | `"versioningStrategy": "Header"` |

Requires `Asp.Versioning.Http` package. See [Resilience & Versioning](references/resilience-versioning.md).

---

## 7. Webhooks & Multi-Part Specs

**Webhooks** — enable in the server marker file:
```json
{
  "generateWebhooks": true,
  "webhookBasePath": "/webhooks"
}
```

**Multi-Part Specs** — merge multiple OpenAPI files:
```json
{
  "multiPartConfiguration": {
    "enabled": true,
    "files": ["pets.yaml", "orders.yaml", "users.yaml"]
  }
}
```

---

## 8. Migration from Old CLI

Migrate from the deprecated `atc-rest-api-generator`:

```bash
# Validate first
atc-rest-api-gen migrate validate --projectPath ./src

# Dry run
atc-rest-api-gen migrate execute --projectPath ./src --dry-run

# Execute migration
atc-rest-api-gen migrate execute --projectPath ./src
```

Changes: project renames, namespace updates, parameter name migration, file restructuring. See [CLI Reference](references/cli-reference.md) for details.

---

## 9. Validation & Spec Checking

```bash
atc-rest-api-gen validate schema --specificationPath PetStore.yaml
```

Three validation levels: `None`, `Standard`, `Strict`. The generator includes 60+ analyzer rules (ATC_API_* prefix) covering naming, security, schema, and operation validation. See [Validation & Analyzer Rules](references/validation-rules.md).

---

## 10. Recommended Packages

| Package | Purpose |
|---|---|
| `Atc.Rest.Api.SourceGenerator` | Core source generator (required) |
| `Atc.Rest.MinimalApi` | Validation filters, global error handler |
| `Atc.Rest.Client` | For EndpointPerOperation client mode |
| `Asp.Versioning.Http` | API versioning support |
Pliki w paczce (9)
  • SKILL.md 10 KB
  • references/cli-reference.md 7 KB
  • references/client-generation.md 5 KB
  • references/marker-files.md 6 KB
  • references/rate-limiting-caching.md 5 KB
  • references/resilience-versioning.md 5 KB
  • references/security.md 4 KB
  • references/server-generation.md 6 KB
  • references/validation-rules.md 5 KB

Wersje

W bazie nie ma innych skilli o nazwie rest-api-generator.

Migawka bazy z 13.11.2026 · wersja paczki 3e5918dff4e4 (skrót SHA-256 całej paczki)

Pobrania w ostatnich 30 dniach: 0 · ranking

Zgłoś problem z tym skillem: szkodliwa treść, błędny opis albo prośba autora o usunięcie.

Podobne skille

  • 100openapi-generator
    Generuje klienty i serwery ze specyfikacji OpenAPI za pomocą OpenAPI Generator, na przykład klienta Java albo serwer Spring, z użyciem CLI, wtyczki Maven i szablonów.
  • 95api-documentation-generator
    Generuje specyfikacje OpenAPI i Swagger oraz dokumentację API z kodu albo projektu.
  • 100openapi-codegen
    Generuje typowane klienty API z OpenAPI przy użyciu openapi-typescript, openapi-generator-cli, swagger-typescript-api i trpc-openapi.
  • 100openapi-spec-generator
    Prawdopodobnie generuje specyfikacje OpenAPI dla interfejsów API i pomaga w budowaniu integracji.
  • 100api-contract
    Projektuje kontrakt OpenAPI między backendem Spring Boot a klientami TypeScript: generuje spec, typowane klienty i sprawdza błędy RFC 9457.
  • 100api-generating
    Generuje kod i dokumentację endpointów API ze specyfikacji: nowe endpointy, handlery tras, szkielety REST API i specyfikacje OpenAPI lub Swagger z kodu.

Uwagi i zgłoszenia

Wiadomość trafi do Bartosza Sokolińskiego. Adres e-mail jest potrzebny tylko do odpowiedzi. Szczegóły w polityce prywatności.