Microservice should cache its OpenAPI document instead of regenerating it on every admin/docs request

[allister-beamable]

Problem

A C# microservice generates its OpenAPI document by reflecting over all of its registered types (routes plus request/response schemas) to build the schema set. This generation runs in full on every GET admin/docs request. On CPU-constrained instances, repeated polling of admin/docs produces repeated full reflection scans and adds significant, avoidable CPU load.

Expected

The OpenAPI document cannot change over the lifetime of a running microservice instance -- its routes and types are fixed at build time. After the document is generated once (at or after boot), admin/docs should return an identical, cached document without re-running the reflection scan.

Actual

Each admin/docs request re-runs the full reflection walk and rebuilds the document from scratch. Observed in production: one complete reflection pass over the service's schema types (hundreds of types) per request, i.e. one CPU-expensive scan for every hit. A client or probe polling admin/docs therefore drives one full scan per poll, which is enough to be a meaningful load on a small instance.

[allister-beamable]

Possible approach: generate the OpenAPI document once (lazily on first admin/docs request, or eagerly at startup) and cache it in memory for the lifetime of the instance, serving the cached copy on subsequent requests. Since the schema is fixed once the process is running, no invalidation is needed -- the cache lives and dies with the instance.

If holding the full document in memory is a concern, cache a serialized (and optionally compressed) copy rather than the object graph; a microservice's OpenAPI document is unlikely to be large enough for this to matter.

[allister-beamable]

Confirming this is current, not a stale-version artifact. AdminRoutes.Docs() builds a fresh document on every request -- new ServiceDocGenerator() then Generate(...) -- with no caching, and this is identical across unity-sdk-3.0.0, unity-sdk-5.1.1, and main (HEAD 2026-06-26). The generator itself is microservice/beamable.tooling.common/OpenAPI/ServiceDocGenerator.cs.

Note there is already a natural cache point: the document is generated once at startup in MicroserviceStartupUtil.GenerateOpenApiSpecification, but Docs() does not reuse that result -- it regenerates from scratch. Retaining the startup-generated document (or memoizing on first Docs() call) would resolve this with a small change.