Working with CLI

🛠️ Working with the atc-rest-api-gen CLI

The atc-rest-api-gen CLI tool provides a command-line interface for setting up projects that use the Atc.Rest.Api.SourceGenerator. It validates OpenAPI specifications, creates project scaffolds, and manages configuration files.

📦 Installation

# Install as a global tool
dotnet tool install -g Atc.Rest.Api.CliGenerator

# Or run directly from source
dotnet run --project src/Atc.Rest.Api.CliGenerator/Atc.Rest.Api.CliGenerator.csproj -- <commands>

📋 Command Overview

atc-rest-api-gen
├── validate
│   └── schema          # ✅ Validate an OpenAPI specification file
├── generate
│   ├── server          # 🖥️ Generate server contracts and domain handler scaffolds
│   └── client          # 📱 Generate a client project
└── options
    ├── create          # 📝 Create a default ApiGeneratorOptions.json file
    └── validate        # ✅ Validate an ApiGeneratorOptions.json file

---

✅ Validate Commands

validate schema

Validates an OpenAPI specification file against the ATC validation rules.

atc-rest-api-gen validate schema -s <PATH> [--no-strict]

⚙️ Options:

Option	Description
-s, --specification <PATH>	(Required) Path to the OpenAPI specification file (YAML or JSON)
--no-strict	Disable strict validation mode

📝 Examples:

# ✅ Validate with strict mode (default)
atc-rest-api-gen validate schema -s api.yaml

# 📋 Validate with standard mode (less strict)
atc-rest-api-gen validate schema -s api.yaml --no-strict

---

⚙️ Generate Commands

🖥️ generate server

Generates server contracts and optionally domain handler scaffolds from an OpenAPI specification.

atc-rest-api-gen generate server -s <PATH> -o <PATH> -n <NAME> [options]

📌 Required Options:

Option	Description
-s, --specification <PATH>	Path to the OpenAPI specification file
-o, --output <PATH>	Output directory for the contracts project
-n, --name <NAME>	Name of the contracts project

🔧 Common Options:

Option	Description
--options <PATH>	Path to ApiGeneratorOptions.json file
--no-strict	Disable strict validation mode
--include-deprecated	Include deprecated operations and schemas
--namespace <NAMESPACE>	Custom namespace prefix

🖥️ Server-Specific Options:

Option	Description
--sub-folder-strategy <STRATEGY>	None, FirstPathSegment, or OpenApiTag
--versioning-strategy <STRATEGY>	None, QueryString, Header, UrlSegment, or Combined
--default-api-version <VERSION>	Default API version (e.g., 1.0)
--domain-output <PATH>	Output path for domain handler scaffolds
--handler-suffix <SUFFIX>	Suffix for handler class names
--stub-implementation <TYPE>	throw-not-implemented, error-501, or default-value

🏗️ Scaffolding Options:

Option	Description
--project-structure <TYPE>	SingleProject, TwoProjects, or TreeProjects (default)
--no-coding-rules	Skip adding ATC coding rules files
--host-ui <TYPE>	None, Swagger, or Scalar (default)
--host-ui-mode <MODE>	DevelopmentOnly (default) or Always
--aspire	Create an Aspire AppHost project

📁 Project Name Overrides:

Option	Description
--host-project <NAME>	Override the host project name
--contracts-project <NAME>	Override the contracts project name
--domain-project <NAME>	Override the domain project name

📛 Namespace Overrides:

Option	Description
--host-namespace <NAMESPACE>	Override the host namespace
--contracts-namespace <NAMESPACE>	Override the contracts namespace
--domain-namespace <NAMESPACE>	Override the domain namespace

📝 Examples:

# 🏗️ Generate server with default settings (TreeProjects mode - 3 projects)
atc-rest-api-gen generate server \
  -s api.yaml \
  -o ./my-api \
  -n DemoApi

# 🔢 Generate server with URL segment versioning
atc-rest-api-gen generate server \
  -s api.yaml \
  -o ./my-api \
  -n DemoApi \
  --versioning-strategy UrlSegment \
  --default-api-version 2.0

# 📦 Single project mode
atc-rest-api-gen generate server \
  -s api.yaml \
  -o output/Demo.Api \
  -n Demo.Api \
  --project-structure SingleProject

# ☁️ Generate with Aspire AppHost
atc-rest-api-gen generate server \
  -s api.yaml \
  -o ./my-api \
  -n DemoApi \
  --aspire

# 📁 Custom project names
atc-rest-api-gen generate server \
  -s api.yaml \
  -o ./my-api \
  -n DemoApi \
  --host-project MyDemoApi \
  --contracts-project Api.Contracts \
  --domain-project MyDemo.DomainStuff

📂 Repository Structure (TreeProjects mode):

my-api/
├── DemoApi.slnx                        # 📋 Solution file
├── .gitignore
├── Directory.Build.props
├── atc-coding-rules-updater.json
├── atc-coding-rules-updater.ps1
├── src/
│   ├── DemoApi.Api/                    # 🖥️ Host project
│   │   ├── DemoApi.Api.csproj
│   │   └── Program.cs
│   ├── DemoApi.Api.Contracts/          # 📝 Contracts project
│   │   ├── DemoApi.Api.Contracts.csproj
│   │   ├── api.yaml
│   │   └── .atc-rest-api-server-contracts
│   ├── DemoApi.Domain/                 # 🏢 Domain project
│   │   ├── DemoApi.Domain.csproj
│   │   ├── api.yaml
│   │   └── .atc-rest-api-server-handlers
│   └── DemoApi.Aspire/                 # ☁️ Aspire AppHost (optional)
│       ├── DemoApi.Aspire.csproj
│       └── Program.cs
└── test/
    └── DemoApi.Tests/
        ├── DemoApi.Tests.csproj
        └── UnitTest1.cs

📱 generate client

Generates a client project from an OpenAPI specification.

atc-rest-api-gen generate client -s <PATH> -o <PATH> -n <NAME> [options]

📌 Required Options:

Option	Description
-s, --specification <PATH>	Path to the OpenAPI specification file
-o, --output <PATH>	Output directory for the client project
-n, --name <NAME>	Name of the client project

📱 Client-Specific Options:

Option	Description
--generation-mode <MODE>	TypedClient or EndpointPerOperation
--client-suffix <SUFFIX>	Suffix for HTTP client class name
--no-oauth	Disable OAuth2 token management generation

📝 Examples:

# 📱 Generate client with TypedClient mode (default)
atc-rest-api-gen generate client \
  -s api.yaml \
  -o output/Demo.Client \
  -n Demo.Client

# 🎯 Generate client with EndpointPerOperation mode
atc-rest-api-gen generate client \
  -s api.yaml \
  -o output/Demo.Client \
  -n Demo.Client \
  --generation-mode EndpointPerOperation

---

⚙️ Options Commands

📝 options create

Creates a default ApiGeneratorOptions.json file.

atc-rest-api-gen options create -o <PATH> [--force]

⚙️ Options:

Option	Description
-o, --output <PATH>	(Required) Output path for the options file
--force	Overwrite existing file if present

✅ options validate

Validates an existing ApiGeneratorOptions.json file.

atc-rest-api-gen options validate -o <PATH>

---

📋 ApiGeneratorOptions.json Configuration

The ApiGeneratorOptions.json file provides centralized configuration for all code generation settings. The CLI auto-discovers this file in:

1. 📍 Explicitly specified via --options <PATH>
2. 📂 Same directory as the OpenAPI specification
3. 📁 Parent directory of the specification
4. 📂 Current working directory

📄 Full Configuration Schema

{
  "general": {
    "validateSpecificationStrategy": "Strict",
    "includeDeprecated": false
  },
  "scaffolding": {
    "projectStructure": "TreeProjects",
    "noCodingRules": false,
    "testFramework": "xunit",
    "targetFramework": "net10.0",
    "hostUi": "Scalar",
    "hostUiMode": "DevelopmentOnly"
  },
  "server": {
    "namespace": null,
    "subFolderStrategy": "FirstPathSegment",
    "useMinimalApiPackage": "auto",
    "useValidationFilter": "auto",
    "useGlobalErrorHandler": "auto",
    "versioningStrategy": "None",
    "defaultApiVersion": "1.0",
    "domain": {
      "generateHandlersOutput": "ApiHandlers",
      "subFolderStrategy": "None",
      "handlerSuffix": "Handler",
      "stubImplementation": "throw-not-implemented"
    }
  },
  "client": {
    "namespace": null,
    "generationMode": "TypedClient",
    "clientSuffix": "Client",
    "generateOAuthTokenManagement": true
  }
}

📚 Configuration Options Reference

🔧 General Options

Option	Type	Default	Description
validateSpecificationStrategy	enum	"Strict"	None, Standard, or Strict
includeDeprecated	bool	false	Include deprecated operations

🏗️ Scaffolding Options

Option	Type	Default	Description
projectStructure	enum	"TreeProjects"	SingleProject, TwoProjects, or TreeProjects
noCodingRules	bool	false	Skip ATC coding rules files
testFramework	string	"xunit"	Test framework for generated test project
targetFramework	string	"net10.0"	Target framework
hostUi	enum	"Scalar"	None, Swagger, or Scalar
hostUiMode	enum	"DevelopmentOnly"	DevelopmentOnly or Always

🖥️ Server Options

Option	Type	Default	Description
namespace	string?	null	Custom namespace (null = auto-detect)
subFolderStrategy	enum	"FirstPathSegment"	None, FirstPathSegment, OpenApiTag
versioningStrategy	enum	"None"	None, QueryString, Header, UrlSegment, Combined
defaultApiVersion	string	"1.0"	Default API version
useMinimalApiPackage	enum	"auto"	auto, enabled, disabled
useValidationFilter	enum	"auto"	auto, enabled, disabled

🏢 Server Domain Options

Option	Type	Default	Description
generateHandlersOutput	string	"ApiHandlers"	Output folder for handlers
subFolderStrategy	enum	"None"	None, FirstPathSegment, OpenApiTag
handlerSuffix	string	"Handler"	Handler class name suffix
stubImplementation	string	"throw-not-implemented"	throw-not-implemented, error-501, default-value

📱 Client Options

Option	Type	Default	Description
namespace	string?	null	Custom namespace (null = auto-detect)
generationMode	enum	"TypedClient"	TypedClient or EndpointPerOperation
clientSuffix	string	"Client"	HTTP client class name suffix
generateOAuthTokenManagement	bool	true	Generate OAuth2 token management

---

🔄 CLI vs Source Generator

The atc-rest-api-gen CLI is a setup tool, not a code generator itself. It:

1. ✅ Validates your OpenAPI specification
2. 📁 Creates project scaffolds with correct structure
3. ⚙️ Configures marker files that trigger the source generator
4. 📝 Generates .csproj files with proper references

The actual code generation happens when you run dotnet build on the created projects.

🔄 Workflow

┌────────────────────────────────────────────────────────────────────┐
│                     🛠️ atc-rest-api-gen CLI                   │
│                                                               │
│  1. ✅ Validates OpenAPI specification                        │
│  2. 📁 Creates project directories                            │
│  3. 📄 Copies specification files                             │
│  4. ⚙️ Creates marker files (.atc-rest-api-*)                 │
│  5. 📝 Creates .csproj files with source generator reference  │
└────────────────────────────────┬───────────────────────────────────┘
                                 │
                                 ▼
┌────────────────────────────────────────────────────────────────────┐
│                       🔨 dotnet build                         │
│                                                               │
│  1. 📖 Source generator reads marker file configuration       │
│  2. 📄 Source generator parses OpenAPI specification          │
│  3. ⚙️ Source generator emits C# code to obj/Generated/       │
│  4. 🔧 Compiler includes generated code in compilation        │
└────────────────────────────────────────────────────────────────────┘

---

🔢 Exit Codes

Code	Description
0	✅ Success
1	❌ Failure (validation errors, file errors, etc.)