Add OpenAPI architecture overview

[PureWeen]

Context

#69011 is the wider effort to add expert pull request review guidance. This PR extracts the durable OpenAPI knowledge into an in-area architecture overview so OpenAPI area owners can review, validate, and merge it independently.

The single-file structure follows the architecture pattern established by @javiercn in #69147, with the sibling SignalR #69200, gRPC #69216, Hosting #69242, and MVC #69243 extractions as additional examples.

Summary

• document how endpoint metadata and MVC ApiExplorer descriptions flow into OpenAPI generation
• describe runtime and build-time document generation, serving, serialization, and cancellation boundaries
• capture document, operation, and schema transformers with their DI and lifetime behavior
• explain schema generation, references, serializer metadata, XML comments, source generation, and trimming/AOT boundaries
• distinguish OpenAPI ownership from Minimal API binding, MVC discovery, generic Routing, OpenAPI.NET, and build tooling
• map focused documentation, verification boundaries, terminology, and adjacent subsystem ownership

Documentation only; no runtime or public API changes.

Validation

• git diff --check passed
• all local Markdown links and heading anchors resolve
• external documentation links resolve
• the effective pull request diff contains exactly one added file: src/OpenApi/ARCHITECTURE.md

[Copilot]

Copilot review overview

🟡 Changes recommended

Unresolved documentation accuracy and lifetime/framework qualification issues remain.

Get a fresh assessment by requesting another Copilot review.

Review tier: Lite
Findings: 2

Open findings (2)

• Qualify which generation paths create a scope · New
• Do not describe options as request-scoped · New

What changed in this PR

This documentation-only PR adds an OpenAPI architecture overview covering generation, transformers, schemas, serving, and subsystem ownership.

Changes:

• Documents runtime and build-time document generation.
• Describes schema, transformer, serialization, trimming, and AOT boundaries.
• Maps verification areas and related subsystem ownership.

File	Description
src/​OpenApi/​ARCHITECTURE.md	Adds the OpenAPI architecture documentation; unresolved accuracy and qualification issues remain.

---

💡 Add a code-review agent skill for context-aware, tailored reviews. Learn more in the docs.