up

docs/api/openapi-discovery.md

@@ -0,0 +1,24 @@
+# OpenAPI Discovery (.well-known/openapi)
+
+As part of OAS-63-002 the platform exposes a discovery document at:
+
+- `/.well-known/openapi` → JSON body:
+  ```json
+  {
+    "spec": "/stella.yaml",
+    "version": "v1",
+    "generatedAt": "<RFC3339>",
+    "extensions": {
+      "x-stellaops-profile": "aggregate",
+      "x-stellaops-schemaVersion": "1.0.0"
+    }
+  }
+  ```
+
+Contracts:
+- `spec` is a relative URL to the aggregate OpenAPI (`stella.yaml`).
+- `version` denotes the discovery doc version; defaults to `v1`.
+- `generatedAt` is the UTC timestamp when the aggregate spec was built.
+- `extensions` carries optional metadata for downstream tooling.
+
+Implementations (API Gateway / Console) should cache the response with `Cache-Control: max-age=300` and serve it alongside the aggregate spec artifact produced by the OAS CI workflow.