GCO API Spec Sheets¶

One spec sheet per HTTP surface of GCO, rendered from the OpenAPI document that describes it: for each FastAPI service the document the application generates itself (the one behind its automatic Swagger /docs page); for each AWS API Gateway the document read out of the synthesized CDK stack; and for the in-cluster Gateway (the internal ALB) the document composed from its HTTPRoute and the service documents. The documents are committed under docs/openapi/, each guarded by a --check in CI, and these sheets are a deterministic rendering of them — so a route, parameter or model change shows up here in the same pull request as the code.

The Swagger UI column is the Swagger console for each document (FastAPI's own /docs page for the services), served from the project site under /swagger/ with a self-hosted copy of swagger-ui-dist (the site makes no third-party requests). It is built at deploy time by pages.yml; the sheets in this directory are also staged into the wiki's source tree under /api/ by scripts/build_wiki.py, so both renderings come from one source.

How the surfaces fit together¶

Drawn from the same documents: a client signs a request with SigV4 to one of the two API Gateways; a Lambda proxy adds the request-bound HMAC envelope and forwards it — over Global Accelerator from the global API, inside the VPC from the regional bridge — to the region's internal ALB, the Kubernetes Gateway whose HTTPRoute picks the Service by longest path prefix. The aggregator answers /api/v1/global/* by fanning out to the regional API Gateways. Dashed arrows are opt-in or dynamic paths; † marks routes that exist only under a deployment condition. Every box is a document in the table above, and each is a link to its sheet on the site.

Regenerating¶

python scripts/generate_openapi.py                  # refresh the service documents from the apps
python scripts/generate_api_gateway_openapi.py      # re-synthesize the API Gateway documents
python scripts/generate_cluster_gateway_openapi.py  # recompose the cluster gateway document
python diagrams/generate.py --api-only              # rewrite these sheets, this index and the diagram
python diagrams/generate.py --check                 # fail if anything here is stale

To browse the consoles locally, install the locked npm tooling and serve the generated tree:

npm ci --ignore-scripts --no-audit --no-fund
python diagrams/api_specs/generate.py --swagger-ui-dir /tmp/gco-swagger \
    --swagger-assets node_modules/swagger-ui-dist
python -m http.server --directory /tmp/gco-swagger 8080

Swagger UI loads the document with a browser request, so the tree has to be served over HTTP rather than opened from the filesystem.