用途:为每个服务组件在 specs/design/components/<name>/openapi.yaml 编写 OpenAPI 3.0.3 规格,用于设计端点、请求/响应模式、错误、分页与安全。
主要能力与要求:以清单驱动覆盖,对照 specs/requirements/prd.md 与组件 design.json 职责,为需求分配给本组件的每项能力提供资源、每个核心实体提供模式;无端点的能力视为缺陷。合并服务时易遗漏审计日志、用户与角色管理、通知偏好、报表分析,需逐一检查。规格保持紧凑:每个操作简短 summary,每个响应一行 description,不写多句描述、示例块或需求未暗示的端点;模式只含必填字段与核心属性。
结构:servers 使用相对地址 - url: /,不用绝对外部主机。路径用 kebab-case 复数名词(/expense-claims、/expense-claims/{claimId}/line-items),仅控制器动作用动词(/expense-claims/{claimId}/submit),最多两层嵌套。每个操作有 lowerCamelCase 的 operationId(如 listExpenseClaims、submitExpenseClaim)和非空 summary;每个响应有非空 description,正文为 application/json,可复用模式放在 components/schemas。
错误:定义 components/schemas/Error 并在所有 4xx/5xx 响应中引用,含 code、message 必填及 description、moreInfo。每个操作声明适用失败模式,如 400/404,认证 API 加 401/403。
分页:每个集合 GET 使用 limit(默认 20,最大 100)与 offset(默认 0),200 响应为信封对象,含 count、next、previous、data,而非裸数组。过滤与搜索作为集合 GET 的查询参数(如 ?status=submitted、?employeeId=...),不单独建端点。
安全:需求提到登录、角色或按用户数据时,声明 bearerAuth(http、bearer、JWT)与 security。网关保护的服务还需在 parameters 中记录注入的 X-User-Id,说明由网关从校验令牌设置、客户端不发送。禁止定义任何认证端点(如 /auth/login、/auth/register、/auth/logout 或令牌签发路径),令牌由 IDP 签发、网关校验。
YAML 规范:统一 2 空格缩进,状态码键加引号('200'、'404'),因后续使用锚定字符串编辑,缩进一致性很重要。
限制:资料未提供具体安装命令、收费或平台信息;详细资源分类、URI 语法、HTTP 方法语义与完整示例需阅读 references/wso2-rest-api-design-guidelines.md。