Add OpenAPI architecture overview

[PureWeen]

Add OpenAPI architecture overview

• You've read the Contributor Guide and Code of Conduct.
• You've included unit or integration tests for your change, where applicable.
• You've included inline docs for your change, where applicable.
• There's an open issue for the PR that you are making. If you'd like to propose a new feature or change, please open an issue to discuss the change or find an existing issue.

Add an OpenAPI architecture reference for contributors and coding agents.

Description

Context

This PR adds src/OpenApi/ARCHITECTURE.md as reference material for contributors and coding agents only, extracting durable OpenAPI technical knowledge into an in-area architecture overview for OpenAPI area-owner validation.

The single-file, in-area structure follows the ARCHITECTURE.md 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 HTTP and MVC producers, OpenAPI.NET, System.Text.Json, hosting features, and build tooling
• map focused documentation, verification boundaries, terminology, and adjacent subsystem ownership

Documentation only: the effective PR diff adds one new file, src/OpenApi/ARCHITECTURE.md. No runtime or public API changes.

Validation

• git diff --check and git diff --check origin/main...HEAD passed
• all repository-relative links in src/OpenApi/ARCHITECTURE.md resolve
• Markdownlint was not run locally
• the effective PR diff contains only the new src/OpenApi/ARCHITECTURE.md file

Related to #69011; this area-specific extraction does not close the wider effort.

[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.

[dotnet-policy-service]

Looks like this PR hasn't been active for some time and the codebase could have been changed in the meantime.
To make sure no conflicting changes have occurred, please rerun validation before merging. You can do this by leaving an /azp run comment here (requires commit rights), or by simply closing and reopening.

[Copilot]

Copilot review overview

🟡 Changes recommended

The document overstates tag-ordering guarantees because operation tags are not ordinally sorted.

Review effort: Balanced
Findings: 1

Open (1)

• Clarify ordering guarantee for document-level tags only · New

Resolved since last review (2)

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