Eternet.AspNetCore.ApiGateway.Generator 1.1.18

Eternet.AspNetCore.ApiGateway.Generator

Eternet.AspNetCore.ApiGateway.Generator projects public API gateway OpenAPI and path rewrite artifacts from endpoint contract manifests.

The package replaces repo-local gateway contract projection tools such as Eternet.Api/src/Generator --contracts-only. Gateway projects should reference their contract packages once, let those references contribute endpoint-model sidecars, and run the package-owned ProjectApiGatewayContracts MSBuild target.

Install

Reference the package from the gateway host project:

<PackageReference Include="Eternet.AspNetCore.ApiGateway.Generator"
                  PrivateAssets="all"
                  IncludeAssets="runtime; build; native; contentfiles; analyzers; buildtransitive" />

Enable projection in the gateway project:

<PropertyGroup>
  <EternetApiGatewayProjectionEnabled>true</EternetApiGatewayProjectionEnabled>
  <EternetApiGatewayProjectionRunOnBuild>false</EternetApiGatewayProjectionRunOnBuild>
  <EternetApiGatewaySourceOpenApiDirectory>$(MSBuildProjectDirectory)\OpenApis\Modules</EternetApiGatewaySourceOpenApiDirectory>
  <EternetApiGatewayOutputOpenApiDirectory>$(MSBuildProjectDirectory)\OpenApis\ApiGatewayModules</EternetApiGatewayOutputOpenApiDirectory>
</PropertyGroup>

Run projection explicitly:

dotnet msbuild src\Eternet.Api.Rest\Eternet.Api.Rest.csproj -t:ProjectApiGatewayContracts -p:Configuration=Release

Inputs

The target consumes:

• AdditionalFiles ending in .eternet.endpoint-model.json, normally produced by referenced contract packages.
• EternetApiGatewayContractManifest items for explicit manifest overrides.
• EternetApiGatewayContractAssembly items for assembly fallback when no sidecar exists.
• source OpenAPI modules from EternetApiGatewaySourceOpenApiDirectory.
• EternetApiGatewaySourceOpenApi items for explicit source OpenAPI modules, either local JSON files or HTTP(S) URLs declared by contract packages.
• existing public gateway OpenAPI modules and path rewrite files as the compatibility baseline.

Do not add a second generator project package-reference list for production projection. The gateway host contract references and sidecars are the source of truth.

MSBuild Properties

MSBuild Items

Explicit EternetApiGatewayContractManifest items take precedence over overlapping AdditionalFiles by destination filename. Assembly fallback is skipped when the matching sidecar was materialized.

Projection Report

The target writes JSON to EternetApiGatewayProjectionReportPath with:

• generatedAtUtc
• sourceOpenApiDirectory
• outputOpenApiDirectory
• pathRewriteDirectory
• projectedOperations
• warnings

Warnings include a stable code, deterministic message, and context fields such as source service, contract assembly, operation name, source path, gateway path, HTTP method, route kind, and authorization source when available.

Warning Codes

Keep EternetApiGatewayFailOnProjectionWarnings=false during migration. Turn it on in CI after known contract metadata gaps are closed or explicitly accepted.

Billing Migration Model

Billing used the old hybrid model:

• source OpenAPI and gateway JSON carried part of the public route metadata;
• contracts carried partial endpoint metadata;
• authorization metadata could drift between contract metadata and generator inference;
• Eternet.Api/src/Generator had its own contract package-reference list.

The contracts-first model is:

• Billing contract packages publish endpoint-model sidecars;
• Eternet.Api.Rest references Billing contracts once;
• ProjectApiGatewayContracts consumes the sidecars and existing gateway JSON compatibility baseline;
• MSBuild writes OpenApis/ApiGatewayModules/*.json, *.pathrewrite.json, and the projection report;
• warnings identify missing source operations, route mismatches, CRUD/auth drift, duplicate public routes, and fallback metadata before approval snapshots drift silently.