Add unified API registry with OpenAPI generation and plugin support

[Copilot]

System lacked centralized management for heterogeneous API types (REST, GraphQL, OData, WebSocket, File, Auth) and plugin-registered endpoints. No unified documentation or testing interface existed.

Implementation

Registry Schema (api/registry.zod.ts)

• ApiProtocolType enum: 10 protocol types (rest, graphql, odata, websocket, file, auth, metadata, plugin, webhook, rpc)
• ApiRegistryEntry: Complete API metadata with endpoints, security, versioning
• ApiDiscoveryQuery: Type/status/tag/plugin-source filtering
• Plugin API tracking via metadata.pluginSource

Documentation Schema (api/documentation.zod.ts)

• OpenApiSpec: Full OpenAPI 3.0 specification generation
• ApiTestingUiConfig: 9 testing UIs (Swagger UI, Redoc, GraphQL Playground, GraphiQL, RapiDoc, Stoplight, Scalar, Postman, custom)
• ApiTestCollection: Postman-like collections with variables, folders, expected responses
• ApiChangelogEntry: Version tracking with migration guides
• CodeGenerationTemplate: Multi-language client generation

Usage

// Register heterogeneous APIs in single registry
const registry = ApiRegistry.create({
  version: '1.0.0',
  apis: [
    ApiRegistryEntry.create({
      id: 'customer_rest',
      type: 'rest',
      endpoints: [/* OpenAPI-compatible metadata */],
    }),
    ApiRegistryEntry.create({
      id: 'payment_webhook',
      type: 'plugin',
      metadata: { pluginSource: 'payment_gateway_plugin' },
      endpoints: [/* ... */],
    }),
  ],
});

// Configure Swagger UI from registry
const docs = ApiDocumentationConfig.create({
  ui: { type: 'swagger-ui', enableTryItOut: true },
  generateOpenApi: true,
});

Plugins register custom endpoints using same ApiRegistryEntry schema as core APIs. OpenAPI specs generated from typed Zod schemas eliminate manual documentation sync.

Original prompt

系统会有很多套Api,包括graphql, odata rest file,auth,包括插件自己注册的Api,如何统一登记管理这些API并且能够提供统一的API查看测试界面比如swagger

---

💡 You can make Copilot smarter by setting up custom instructions, customizing its development environment and configuring Model Context Protocol (MCP) servers. Learn more Copilot coding agent tips in the docs.

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Actions	Updated (UTC)
spec	Ready	Preview, Comment	Feb 2, 2026 5:51am

[Copilot]

Pull request overview

This PR implements a comprehensive Unified API Registry and Documentation System that addresses the core problem of managing heterogeneous API types (REST, GraphQL, OData, WebSocket, File, Auth, and Plugin-registered APIs) in a centralized manner with OpenAPI generation and interactive testing interfaces.

Changes:

• Added centralized API registry protocol supporting 10 API types with complete metadata tracking
• Implemented OpenAPI 3.0 specification generation with support for 9 interactive testing UIs (Swagger UI, Redoc, GraphQL Playground, GraphiQL, RapiDoc, Stoplight, Scalar, Postman, custom)
• Added advanced features including RBAC integration, dynamic schema linking (ObjectQL references), protocol extensibility, and priority-based route conflict resolution

Reviewed changes

Copilot reviewed 35 out of 35 changed files in this pull request and generated 1 comment.

Show a summary per file

File	Description
packages/spec/src/api/registry.zod.ts	Core API registry protocol with 848 lines defining 10 protocol types, endpoint registration, discovery queries, and conflict resolution strategies
packages/spec/src/api/documentation.zod.ts	OpenAPI spec generation schemas, testing UI configurations (9 types), test collections, changelog tracking, and code generation templates
packages/spec/src/api/registry.test.ts	Comprehensive test suite with 992 lines covering all registry features including RBAC, dynamic schemas, priorities, and protocol configs
packages/spec/src/api/documentation.test.ts	Test suite with 617 lines validating OpenAPI specs, UI configs, test collections, and changelog entries
packages/spec/src/api/registry.example.ts	Production-ready examples demonstrating RBAC, dynamic schemas, protocol extensibility, and route priorities
packages/spec/src/api/index.ts	Export statements for new registry and documentation modules
examples/api-registry-example.ts	Complete usage example with 605 lines demonstrating REST, GraphQL, and Plugin API registration with Swagger UI configuration
packages/spec/json-schema/api/*.json	24 generated JSON schema placeholder files for new types (populated by build script)
content/docs/references/api/meta.json	Documentation index updated with registry and documentation entries
content/docs/references/api/index.mdx	Documentation cards added for new API modules
IMPLEMENTATION_SUMMARY.md	Comprehensive implementation summary documenting problem statement, solution, and benefits
API_REGISTRY_ENHANCEMENTS.md	Detailed documentation of four key enhancements (RBAC, dynamic schemas, protocol extensibility, conflict detection)

[Copilot]

The file reference path in the JSDoc @see tag is incorrect. The path file://../../permission/permission.zod.ts uses a relative path that doesn't match the actual file structure.

Since this file is at packages/spec/src/api/registry.zod.ts and the permission file is at packages/spec/src/permission/permission.zod.ts, the correct relative path should be ../permission/permission.zod.ts (one level up, not two).