api-designer

API Designer 是一款专注于 REST 与 GraphQL API 架构设计的专业文档型技能，旨在为开发团队提供企业级的接口设计规范与最佳实践指导。

核心用法
该技能通过结构化的六步工作流（领域分析、资源建模、端点设计、契约规范、演进规划）协助用户构建完整的 API 体系。它支持生成符合 OpenAPI 3.1 标准的规范文档，涵盖资源关系映射、HTTP 方法语义、URI 设计模式、分页策略（游标/偏移/键集）、错误处理（RFC 7807 Problem Details）以及认证流程（OAuth 2.0/JWT）等关键环节。用户可通过触发"API design"、"OpenAPI"等关键词调用该技能，获取从架构规划到文档输出的全流程指导。

显著优点
首先，内容权威性高，基于 10+ 年架构经验的行业最佳实践，严格遵循 REST 原则与 HTTP 语义，避免常见设计反模式（如在 URI 中使用动词）。其次，约束条件明确，通过 MUST DO 与 MUST NOT DO 清单确保设计质量，强制要求版本控制、分页实现、错误标准化等生产级要素。第三，参考体系完善，提供 REST 模式、版本控制、分页、错误处理等专题参考文档，形成可复用的知识库。最后，输出模板完整，不仅提供概念指导，还包含可直接使用的 OpenAPI YAML/JSON 模板、错误响应目录及 SDK 生成建议。

潜在缺点与局限性
作为纯文档型技能，其最大局限在于无自动化执行能力——无法直接生成服务端代码、执行 API 测试或验证规范语法，仅提供设计指导与模板参考。此外，来源为 T3 级社区个人账号（veeramanikandanr48），缺乏企业级背书与广泛社区验证，内容更新频率与长期维护存在不确定性。对于高度定制化的业务场景，其标准化建议可能需要大量调整才能适配特定技术栈。

适合的目标群体
主要面向后端架构师、全栈开发者、技术负责人及 API 产品经理。特别适合需要建立 API 设计规范的中大型开发团队、正在进行系统微服务化改造的企业，以及需要输出标准化 OpenAPI 文档供前端或第三方集成的场景。对于正在学习 RESTful 设计的初级开发者，该技能也是理解行业标准的优质教材。

使用风险
该技能本身为静态文档，无代码执行、网络通信或数据收集行为，不存在运行时安全风险。但用户需注意：1）文档中的代码示例仅为演示用途，直接复制到生产环境可能不适用于具体框架；2）设计建议基于通用最佳实践，与特定语言（如 Python FastAPI、Java Spring Boot）的实现细节可能存在差异，需结合具体技术栈调整；3）作为 T3 来源内容，建议关键架构决策前交叉验证其他权威资料。