Decentralize OpenAPI Specs to Owning Projects

Objective

Move OpenAPI specifications from technical-guide to their respective owning projects. Each microservice owns its API contract.

Specs to Relocate

Move to Projects

• `components/studio-ui-api.yaml` → `common_npm/studio-ui/openapi/openapi.yaml`
• `components/agent-mesh-api.yaml` → `common_npm/agent-mesh/openapi/openapi.yaml`
• `components/design-system-api.yaml` → `common_npm/studio-ui/openapi/design-system.yaml`
• `components/unified-platform-api.yaml` → `agent-router/openapi/unified-platform.yaml`
• `components/platform-monitor-openapi.yaml` → `agent-router/openapi/platform-monitor.yaml`
• `components/ossa-registry.v1.yaml` → `OSSA/openapi/registry.yaml`
• `components/self-evolving-ecosystem-v1.yaml` → `agent-router/openapi/ecosystem.yaml`
• `components/agent-buildkit-api.yaml` → Verify already at correct location

Update Projects

• Each project includes spec in published npm package
• Each project exposes spec at runtime via `/openapi.json` endpoint
• Update package.json to include openapi directory in files
• Update CI/CD to validate specs on changes

Verify agent-buildkit Locations

• Check all `common_npm/*` packages have `openapi/openapi.yaml`
• Standardize naming: use `openapi/openapi.yaml` consistently

Related

• Epic: #1
• Previous: #3 (design-system-api migration)
• Next: #5 (create central registry index)
• Depends on: #2, #3 (service migrations)

Rationale

Microservice best practice: each service's API contract is maintained alongside the service itself, ensuring consistency and ease of versioning.

Testing

• Verify each spec is valid OpenAPI 3.1
• Contract tests pass in each project
• Specs are accessible in npm packages