Contrato OpenAPI TypeScript

Contrato para el frontend (OpenAPI → TypeScript)

Los TypedResults de los handlers describen cada endpoint automáticamente — requests, responses y status codes salen del código, sin atributos ni anotaciones. El documento OpenAPI está disponible de dos formas:

• En runtime: GET /openapi/v1.json, y una UI interactiva en /scalar/v1 (Scalar) — ambas registradas en Common/OpenApi/OpenApiRegistration.cs y solo habilitadas en Development y Staging; en Production no se publica el contrato ni una UI para explorar/probar la API.
• En build: cada dotnet build emite src/VsaTemplate/openapi/VsaTemplate.json (vía Microsoft.Extensions.ApiDescription.Server). Commitéalo: el frontend genera desde el archivo sin necesitar la API corriendo, y su diff en los PRs documenta cada cambio de contrato.

Desde Angular, genera los tipos y servicios con un comando (agrégalo como script de npm y córrelo cuando cambie el contrato):

# Opción 1 — servicios Angular completos (modelos + servicios con HttpClient):
npx ng-openapi-gen --input ../VsaTemplate/src/VsaTemplate/openapi/VsaTemplate.json --output src/app/api

# Opción 2 — solo los tipos (tú escribes las llamadas HTTP):
npx openapi-typescript ../VsaTemplate/src/VsaTemplate/openapi/VsaTemplate.json -o src/app/api/schema.d.ts

El flujo completo: cambias un record en C# → dotnet build actualiza el JSON → npx ng-openapi-gen regenera el TypeScript → el compilador de TypeScript marca todo lo que quedó desactualizado en Angular.

Dos piezas hacen que el contrato salga limpio (ya configuradas en Common/OpenApi/OpenApiRegistration.cs):

• .WithName(nameof(CreateProduct)) en cada mapeo define el operationId, que es el nombre del método en el cliente generado.
• CreateSchemaReferenceId en AddOpenApiDocument() prefija los records anidados con su clase contenedora (CreateProduct.Request → CreateProductRequest); sin esto, los Request/Response de distintos slices colisionan en el documento.

---

Ver también: Composicion-en-Program-cs · Home