OpenAPI as an observable contract

A generated API description is a contract artifact

OpenAPI gives tools a structured description of HTTP operations, parameters and representations. It does not start a server on its own or guarantee that every described branch works. The external project registers first-party ASP.NET Core 10 OpenAPI services and exposes the generated document only in Development. Its package reference is explicitly pinned to the verified version. The portable companion instead compares two sets of outcome names. That small check illustrates description drift without pretending to generate OpenAPI, host documentation or parse the real server's schema inside the embedded console.

Observe a matching description and an intentional omission

The console begins with documented and implemented outcome sets containing found and missing. Set equality prints matched. It then removes missing from the documented set and prints missing outcome. On the real server, a typed endpoint describes successful item lookup and absence, and /openapi/v1.json exposes those alternatives under the item path. A request for identifier one returns the item while nine returns 404. The server's generated document and its real outcomes are complementary observations; the console's set example merely explains why a description can drift when an alternative is omitted.

Typed results contribute useful but bounded metadata

The endpoint names its operation and supplies a summary while its typed union exposes 200 and 404 alternatives. The route parameter is an integer, so the generated document can describe that input. Metadata should remain aligned with actual behavior, especially when adding new failure branches or representations. A generated document cannot discover a business guarantee that the code never expresses, nor can it prove that an external dependency fulfills its contract. Inspect the paths and schemas clients will actually consume rather than assuming that a successful AddOpenApi call implies every important policy is documented correctly.

A document endpoint is separate from a visual UI

MapOpenApi exposes the serialized document; this project adds no interactive Swagger UI or other documentation frontend. The Development guard is an intentional exposure choice, so requesting the same document in Production should not be treated as proof of a broken item endpoint. Decide how a deployed system makes its contract available and whether that artifact belongs behind a specific access boundary. Avoid attaching an unreviewed UI package merely because a browser displays JSON. A valid document can be downloaded, checked into an integration workflow or consumed by tooling without any UI running inside the application.

Practice: compare a new response branch with the document

Add a separately specified invalid-identifier result to the item endpoint, update its typed alternatives and rebuild. Inspect whether the generated responses now include the intended status and representation. Then request that branch directly. Keep a copy of the previous document and identify the precise contract change instead of comparing raw JSON formatting. The hint is to inspect operation responses and referenced schemas structurally. A branch that returns the expected status at runtime but is missing from the generated description is a different failure from a document describing a branch the handler never executes.

Practice: verify environment-specific availability

Run the same compiled project once in Development and once in Production on separate owned loopback ports. Predict which run exposes /openapi/v1.json and whether both should still serve /items/1. Stop each owned process after checking it. Then decide how a client-generation workflow would obtain the document without depending on a production UI. This exercise separates documentation exposure from application functionality. Do not change route behavior while changing the environment; otherwise a missing item response could be incorrectly attributed to the OpenAPI guard instead of an independent configuration difference.

Use generated documents and request tests together

A useful review examines operation identity, parameter source and type, response alternatives and schema shape, then checks representative requests against those expectations. The supplied project establishes a small real example of that workflow with no database or remote service. Preserve explicit package versions when reproducing the lab, and inspect document changes when upgrading the framework or changing endpoint types. The console remains useful for the general idea of contract drift, but only the external project's generated artifact represents this API. Keep that distinction visible when claiming what was compiled, described and actually exercised through HTTP.

• Inspect generated document structure and real response branches independently.
• MapOpenApi exposes a document; a visual documentation UI is a separate component.