Working with Configuration

⚙️ Working with Configuration

This guide covers the ApiGeneratorOptions.json configuration file and the CLI commands for managing it.

---

📄 ApiGeneratorOptions.json

The ApiGeneratorOptions.json file controls how the generator behaves. It's auto-discovered from your project directory, or you can specify it explicitly with --options.

📝 Creating a Configuration File

# Create with defaults in the current directory
atc-rest-api-gen options create -o .

# Create at a specific path
atc-rest-api-gen options create -o ./config/ApiGeneratorOptions.json

# Overwrite existing file
atc-rest-api-gen options create -o . --force

📋 Default Configuration

{
  "general": {
    "validateSpecificationStrategy": "Standard",
    "includeDeprecated": false
  },
  "server": {
    "namespace": null,
    "subFolderStrategy": "BySegment",
    "versioningStrategy": "None",
    "defaultApiVersion": "1.0",
    "reportApiVersions": true,
    "assumeDefaultVersionWhenUnspecified": true,
    "useServersBasePath": false,
    "useGlobalErrorHandler": "Auto",
    "useMinimalApiPackage": "Auto",
    "domain": {
      "generateHandlersOutput": "Handlers",
      "handlerSuffix": "Handler",
      "stubImplementation": "NotImplementedException"
    }
  },
  "client": {
    "namespace": null,
    "generationMode": "EndpointPerOperation",
    "clientSuffix": "Endpoint",
    "httpClientName": null,
    "generatePartialModels": false,
    "generateOAuthTokenManagement": false,
    "useServersBasePath": true,
    "includePaths": [],
    "excludePaths": []
  }
}

---

✅ Validating Configuration

The options validate command checks your configuration file for errors and displays a summary:

# Validate options file in current directory
atc-rest-api-gen options validate -o .

# Validate a specific file
atc-rest-api-gen options validate -o ./config/ApiGeneratorOptions.json

🔍 What Gets Validated

Check	Description
📄 File exists	Verifies the JSON file is found at the specified path
🔧 JSON syntax	Validates the file is well-formed JSON
📋 Known properties	Warns about unrecognized property names (typos)
🔢 Valid enum values	Checks that strategy/mode values are valid (e.g., EndpointPerOperation, TypedClient)
🔗 Namespace format	Validates namespace strings follow C# naming rules
📁 Path references	Checks that referenced paths/directories are valid

📊 Output Example

✓ Validation passed - options file is valid

Configuration summary:
┌─────────────────┬──────────────────────────────────┬───────────────────────────┐
│ Section        │ Setting                        │ Value                   │
├─────────────────┼──────────────────────────────────┼───────────────────────────┤
│ general        │ validateSpecificationStrategy  │ Standard                │
│ general        │ includeDeprecated              │ False                   │
│ server         │ namespace                      │ (auto-detect)           │
│ server         │ subFolderStrategy              │ BySegment               │
│ server         │ versioningStrategy             │ None                    │
│ server         │ defaultApiVersion              │ 1.0                     │
│ server.domain  │ generateHandlersOutput         │ Handlers                │
│ server.domain  │ handlerSuffix                  │ Handler                 │
│ server.domain  │ stubImplementation             │ NotImplementedException │
│ client         │ namespace                      │ (auto-detect)           │
│ client         │ generationMode                 │ EndpointPerOperation    │
│ client         │ clientSuffix                   │ Endpoint                │
│ client         │ generateOAuthTokenManagement   │ False                   │
└─────────────────┴──────────────────────────────────┴───────────────────────────┘

---

🔧 Configuration Reference

📋 General Section

Setting	Type	Default	Description
validateSpecificationStrategy	enum	Standard	None, Minimal, Standard, Strict — how strictly to validate the OpenAPI spec
includeDeprecated	bool	false	Whether to include deprecated operations and schemas

🖥️ Server Section

Setting	Type	Default	Description
namespace	string	auto	Override the generated namespace (defaults to project name)
subFolderStrategy	enum	BySegment	How to organize generated files in subfolders
versioningStrategy	enum	None	None, QueryString, UrlSegment, Header
defaultApiVersion	string	"1.0"	Default API version when unspecified
reportApiVersions	bool	true	Include version info in response headers
assumeDefaultVersionWhenUnspecified	bool	true	Use default version when client doesn't specify
useServersBasePath	bool	false	Prepend base path from OpenAPI servers[0].url to routes
useGlobalErrorHandler	enum	Auto	Auto, Enabled, Disabled — GlobalErrorHandlingMiddleware
useMinimalApiPackage	enum	Auto	Auto, Enabled, Disabled — Atc.Rest.MinimalApi package

🏥 Health Check Section

Setting	Type	Default	Description
healthChecks.enabled	bool	false	Generate health check endpoints
healthChecks.path	string	"/health"	Base path for health endpoints
healthChecks.includeLiveness	bool	true	Generate /health/live liveness probe
healthChecks.includeReadiness	bool	true	Generate /health/ready readiness probe
healthChecks.security	string	"none"	"none" or "apiKey" (query param + header)
healthChecks.apiKeyQueryParameterName	string	"api-key"	Query parameter name for API key
healthChecks.apiKeyHeaderName	string	"X-Health-Api-Key"	Header name for API key

💡 When security: "apiKey", the API key is read from IConfiguration["HealthChecks:ApiKey"] at runtime. If the config value is empty, the filter passes through (no security).

⚠️ If your OpenAPI spec already defines paths under the health check base path (e.g., /health), the generator emits a ATC_API_DEP009 warning about duplicate endpoint registration.

🖥️ Server Domain Section

Setting	Type	Default	Description
generateHandlersOutput	string	"Handlers"	Directory for generated handler scaffolds
handlerSuffix	string	"Handler"	Suffix for handler class names
stubImplementation	string	"NotImplementedException"	Default stub: NotImplementedException or TodoComment
injectLogger	bool	false	Inject ILogger<T> constructor parameter into handler scaffolds
injectTracing	bool	false	Inject ActivitySource for OpenTelemetry distributed tracing
maxLineLength	int	80	Max line length for code formatting. Match dotnet_diagnostic.ATC201.max_line_length in .editorconfig

🔌 Client Section

Setting	Type	Default	Description
namespace	string	auto	Override the generated namespace
generationMode	enum	EndpointPerOperation	EndpointPerOperation or TypedClient
clientSuffix	string	"Endpoint"	Suffix for client/endpoint class names
httpClientName	string	auto	Override the IHttpClientFactory named client
generatePartialModels	bool	false	Generate partial records for extensibility
generateOAuthTokenManagement	bool	false	Generate OAuth token refresh infrastructure
useServersBasePath	bool	true	Prepend base path from OpenAPI servers[0].url to URLs
includePaths	string[]	[]	Glob patterns to include (e.g., ["/pets/*", "/users/*"])
excludePaths	string[]	[]	Glob patterns to exclude (e.g., ["/internal/*"])

---

🔄 Marker Files vs Options File

The generator supports two configuration approaches:

Approach	Best For	How It Works
Marker files (.atc-rest-api-server, etc.)	Simple projects	JSON config embedded in the marker file, per-project
ApiGeneratorOptions.json	Multi-project solutions	Shared config file, referenced by marker files or auto-discovered

Marker file settings override options file settings when both are present.

💡 See Marker Files for the complete marker file reference.

---

🔗 Related Guides

• Marker Files — Marker file configuration reference
• Working with OpenAPI — OpenAPI specification patterns
• Working with Versioning — API versioning configuration
• Working with Security — Security scheme configuration