OpenAPI REST API
使用 oRPC 契约构建外部 REST API 并自动生成 OpenAPI 文档
OpenAPI REST API
ProductReady 包含使用 oRPC 契约优先 构建的 REST API，并自动生成 OpenAPI 文档。它适合外部集成、移动应用、服务间调用，以及非 TypeScript 客户端。
ProductReady 前端优先使用 tRPC。其他系统需要 HTTP/OpenAPI 接口或生成 SDK 时，使用 REST API。
Contract 导出
REST contract 和 client 从轻量 oRPC 集成层 ~/lib/orpc 导出：
import {
createProductReadyOpenApiClient,
productreadyOpenApiContract,
} from "~/lib/orpc";
const client = createProductReadyOpenApiClient({
baseUrl: "https://your-app.com",
apiKey: process.env.PRODUCTREADY_API_KEY,
});
const me = await client.users.me();外部 TypeScript 包如果要自己创建 oRPC client，可以直接复用 productreadyOpenApiContract。
API 文档访问方式
Swagger UI
交互式 API 浏览器，支持在线测试
OpenAPI JSON
原始 OpenAPI 3.0 规范，用于工具和 SDK
API Reference
从 OpenAPI schema 渲染的集成文档
项目结构
src/
├── app/api/v1/[[...server]]/
│ ├── app.ts # 测试兼容的 request wrapper
│ └── route.ts # Next.js route handler
├── domains/openapi/
│ ├── auth.ts # 普通 REST endpoint 的 API key 认证
│ ├── contract.ts # 普通 REST oRPC contract 与 Zod schemas
│ └── router.ts # 普通 REST contract 实现
├── domains/systemadmin/openapi/
│ ├── auth.ts # System admin secret 认证
│ ├── contract.ts # System admin oRPC contract
│ └── router.ts # System admin 实现
└── lib/orpc/
├── client.ts # 类型安全 oRPC/OpenAPI client helper
├── spec.ts # OpenAPI spec 生成
├── http.ts # Fetch handler 与 Swagger UI
└── index.ts # 公开导出新增端点
先在所属 domain 的 contract 添加 procedure，例如 src/domains/openapi/contract.ts：
import { oc } from "@orpc/contract";
import { z } from "zod";
export const hello = oc
.route({
method: "GET",
path: "/api/v1/hello",
tags: ["General"],
summary: "Say hello",
})
.output(z.object({ message: z.string(), timestamp: z.string() }));再到对应 domain router 实现，例如 src/domains/openapi/router.ts：
hello: os.hello.handler(() => ({
message: "Hello from ProductReady!",
timestamp: new Date().toISOString(),
}));同一份 contract 会驱动运行时 handler、/api/v1/openapi.json、Swagger UI 和 TypeScript client。
认证
受保护端点使用 Bearer token：
curl -H "Authorization: Bearer YOUR_API_KEY" \
http://localhost:3000/api/v1/users/me/api/v1/system-admin/* 下的系统管理端点需要全局 system admin secret，或 system admin API key。
快速开始
curl http://localhost:3000/api/v1/health
curl http://localhost:3000/api/v1/openapi.json测试
app.request() wrapper 会保留给现有集成测试使用：
import { app } from "../src/app/api/v1/[[...server]]/app";
const response = await app.request("/api/v1/health");
expect(response.status).toBe(200);需要 client contract 检查时，从 ~/lib/orpc 导入 createProductReadyOpenApiClient。