Analyzer Rules

📋 Analyzer Rules Reference

This document provides a comprehensive reference for all diagnostic rules implemented in the Atc.Rest.Api.SourceGenerator.

🔢 Rule ID Format

All rule IDs follow the pattern: ATC_API_[CAT][NNN]

• ATC_API - Prefix for all rules
• [CAT] - 3-letter category code
• [NNN] - 3-digit rule number

📑 Categories

Category	Code	Description
⚙️ Generation	GEN	Code generation errors and warnings
📦 Dependencies	DEP	Package/assembly dependency requirements
✅ Validation	VAL	OpenAPI specification parsing and validation
📝 Naming	NAM	Naming convention rules
🔒 Security	SEC	Security configuration validation
🖥️ Server	SRV	Server URL validation
📄 Schema	SCH	Schema definition validation
🛤️ Path	PTH	Path definition validation
🎯 Operation	OPR	Operation definition validation

---

⚙️ Generation Rules (GEN)

Rules related to code generation errors and warnings.

Rule ID	Severity	Description
ATC_API_GEN001	❌ Error	OpenAPI server generation error
ATC_API_GEN002	❌ Error	OpenAPI server parsing error
ATC_API_GEN003	❌ Error	OpenAPI client generation error
ATC_API_GEN004	❌ Error	OpenAPI client parsing error
ATC_API_GEN005	❌ Error	Handler scaffold generation error
ATC_API_GEN006	❌ Error	OpenAPI domain parsing error
ATC_API_GEN007	⚠️ Warning	Output directory not specified
ATC_API_GEN008	❌ Error	Endpoint injection generation error
ATC_API_GEN009	⚠️ Warning	No endpoints found for endpoint injection

---

📦 Dependency Rules (DEP)

Rules related to required package and assembly references.

Rule ID	Severity	Description	Required Package
ATC_API_DEP001	❌ Error	Server generator requires ASP.NET Core	Microsoft.AspNetCore.App
ATC_API_DEP002	❌ Error	Domain generator requires ASP.NET Core	Microsoft.AspNetCore.App
ATC_API_DEP003	❌ Error	EndpointPerOperation mode requires Atc.Rest.Client	Atc.Rest.Client
ATC_API_DEP004	⚠️ Warning	Rate limiting extensions detected	Microsoft.AspNetCore.RateLimiting
ATC_API_DEP005	⚠️ Warning	Resilience extensions detected	Microsoft.Extensions.Http.Resilience
ATC_API_DEP006	⚠️ Warning	JWT Bearer security scheme detected	Microsoft.AspNetCore.Authentication.JwtBearer
ATC_API_DEP007	❌ Error	useMinimalApiPackage enabled but package not referenced	Atc.Rest.MinimalApi

---

✅ Validation Rules (VAL)

Rules related to OpenAPI specification parsing and validation.

Rule ID	Severity	Description
ATC_API_VAL001	❌ Error	OpenAPI core parsing error from Microsoft.OpenApi library
ATC_API_VAL002	❌ Error	OpenAPI 2.0 (Swagger) not supported - must use OpenAPI 3.0.x

---

📝 Naming Convention Rules (NAM)

Rules enforcing naming conventions in OpenAPI specifications.

Rule ID	Severity	Description	Expected Convention
ATC_API_NAM001	⚠️ Warning	OperationId must start with lowercase letter	camelCase
ATC_API_NAM002	⚠️ Warning	Model name must use correct casing	PascalCase
ATC_API_NAM003	⚠️ Warning	Property name must use correct casing	camelCase
ATC_API_NAM004	⚠️ Warning	Parameter name must use correct casing	camelCase
ATC_API_NAM005	⚠️ Warning	Enum value must use correct casing	PascalCase or UPPER_SNAKE_CASE
ATC_API_NAM006	⚠️ Warning	Tag name must use correct casing	kebab-case

---

🔒 Security Rules (SEC)

Rules validating security configuration in OpenAPI specifications.

Rule ID	Severity	Description
ATC_API_SEC001	❌ Error	Path authorize role not defined in global section
ATC_API_SEC002	❌ Error	Path authentication scheme not defined in global section
ATC_API_SEC003	❌ Error	Operation authorize role not defined in global section
ATC_API_SEC004	❌ Error	Operation authentication scheme not defined in global section
ATC_API_SEC005	⚠️ Warning	Operation has authenticationRequired=false but has roles/schemes
ATC_API_SEC006	⚠️ Warning	Operation authorize role has incorrect casing vs global section
ATC_API_SEC007	⚠️ Warning	Operation authentication scheme has incorrect casing vs global
ATC_API_SEC008	⚠️ Warning	Path authorize role has incorrect casing vs global section
ATC_API_SEC009	⚠️ Warning	Path authentication scheme has incorrect casing vs global
ATC_API_SEC010	⚠️ Warning	Path has authenticationRequired=false but has roles/schemes

---

🖥️ Server Rules (SRV)

Rules validating server configuration in OpenAPI specifications.

Rule ID	Severity	Description
ATC_API_SRV001	❌ Error	Invalid server URL format

---

📄 Schema Rules (SCH)

Rules validating schema definitions in OpenAPI specifications.

Rule ID	Severity	Description
ATC_API_SCH001	⚠️ Warning	Missing title on array type
ATC_API_SCH002	⚠️ Warning	Array type title not starting with uppercase
ATC_API_SCH003	⚠️ Warning	Missing title on object type
ATC_API_SCH004	⚠️ Warning	Object type title not starting with uppercase
ATC_API_SCH005	❌ Error	Implicit object definition in array property not supported
ATC_API_SCH006	⚠️ Warning	Object name not using correct casing style
ATC_API_SCH007	⚠️ Warning	Object property name not using correct casing style
ATC_API_SCH008	⚠️ Warning	Enum name not using correct casing style
ATC_API_SCH009	❌ Error	Array property missing data type specification
ATC_API_SCH010	❌ Error	Implicit object definition on property not supported
ATC_API_SCH011	❌ Error	Array property missing items specification
ATC_API_SCH012	❌ Error	Missing key/name for object property
ATC_API_SCH013	❌ Error	Schema reference does not exist in components.schemas

---

🛤️ Path Rules (PTH)

Rules validating path definitions in OpenAPI specifications.

Rule ID	Severity	Description
ATC_API_PTH001	❌ Error	Path parameters not well-formatted (unbalanced braces)

---

🎯 Operation Rules (OPR)

Rules validating operation definitions in OpenAPI specifications.

Rule ID	Severity	Description
ATC_API_OPR001	❌ Error	Missing operationId
ATC_API_OPR002	⚠️ Warning	OperationId not using correct casing style
ATC_API_OPR003	⚠️ Warning	GET operationId should start with 'Get' or 'List'
ATC_API_OPR004	⚠️ Warning	POST operationId should not start with 'Delete'
ATC_API_OPR005	⚠️ Warning	PUT operationId should start with 'Update'
ATC_API_OPR006	⚠️ Warning	PATCH operationId should start with 'Patch' or 'Update'
ATC_API_OPR007	⚠️ Warning	DELETE operationId should start with 'Delete' or 'Remove'
ATC_API_OPR008	⚠️ Warning	Pluralized operationId but response is single item
ATC_API_OPR009	⚠️ Warning	Singular operationId but response is array
ATC_API_OPR010	⚠️ Warning	Has BadRequest response but no parameters
ATC_API_OPR011	❌ Error	Global path parameter not present in route
ATC_API_OPR012	❌ Error	Operation missing path parameter defined in route
ATC_API_OPR013	❌ Error	Operation path parameter not present in route
ATC_API_OPR014	⚠️ Warning	GET with path parameter missing NotFound response
ATC_API_OPR015	⚠️ Warning	Path parameter missing required=true
ATC_API_OPR016	⚠️ Warning	Path parameter must not be nullable
ATC_API_OPR017	❌ Error	RequestBody with inline model not supported
ATC_API_OPR018	❌ Error	Multiple 2xx status codes not supported
ATC_API_OPR021	⚠️ Warning	401 Unauthorized response defined but no security requirements
ATC_API_OPR022	⚠️ Warning	403 Forbidden response defined but no authorization requirements
ATC_API_OPR023	⚠️ Warning	404 NotFound response on POST operation is unusual
ATC_API_OPR024	⚠️ Warning	409 Conflict response on non-mutating operation (GET/DELETE)
ATC_API_OPR025	⚠️ Warning	429 TooManyRequests response but no rate limiting configured

---

🔇 Suppressing Rules

Rules can be suppressed using standard .NET analyzer suppression techniques:

💻 In Source Code

#pragma warning disable ATC_API_NAM001
// Code that triggers the warning
#pragma warning restore ATC_API_NAM001

⚙️ In .editorconfig

[*.yaml]
dotnet_diagnostic.ATC_API_NAM001.severity = none

📄 In Project File

<PropertyGroup>
  <NoWarn>$(NoWarn);ATC_API_NAM001</NoWarn>
</PropertyGroup>

---

⚖️ Validation Strategies

The source generator supports different validation strategies:

Strategy	Description
🚫 None	No validation rules are applied
📋 Standard	Only error-level rules are enforced
🔒 Strict	All rules (errors and warnings) are enforced

⚙️ Configure via marker file:

{
  "validateSpecificationStrategy": "Strict"
}