Create Central API Registry Index (Discovery Metadata)

Objective

Transform technical-guide's OpenAPI registry into a discovery index that points to distributed specs rather than storing them.

Tasks

Transform registry.yaml

• Convert from full spec aggregation to discovery index
• Each entry includes: name, package, repository, specPath, version, domain, category, status
• Schema defines ApiSpec metadata structure
• Include service discovery endpoints
• Add automation metadata (last updated, generated by)

Transform platform-index.yaml

• Update to reflect distributed spec locations
• Automated generation from scanning projects
• Track spec counts per project
• Include version information

Registry Structure

```yaml apis:

• name: Studio UI package: "@ossa/studio-ui" repository: common_npm/studio-ui specPath: openapi/openapi.yaml specUrl: https://registry.npmjs.org/@ossa/studio-ui/openapi.yaml version: 2.0.0 domain: studio.local.bluefly.io category: frontend status: stable endpoints: openapi: http://studio.local.bluefly.io/openapi.json health: http://studio.local.bluefly.io/health ```

Automation

• Create `buildkit openapi discover` command to regenerate index
• Scan all projects in monorepo for openapi/ directories
• Extract metadata from each spec
• Update registry.yaml and platform-index.yaml
• Run in CI to keep index fresh

Validation

• Schema validation for registry structure
• Verify all referenced paths exist
• Check versions match package.json
• Ensure no duplicate services

Related

• Epic: #1
• Previous: #4 (decentralize specs)
• Next: #6 (migrate docs to wiki)
• Depends on: #4 (specs must be moved first)

Benefits

• Single source of truth for service discovery
• No duplication of OpenAPI specs
• Easy to see what APIs exist in ecosystem
• Automation keeps it accurate