关于 701-technologies-openapi
用于设计、审查和验证 OpenAPI 3.x 契约的 Skill，侧重契约质量与治理。内容涵盖文档结构、操作、可复用组件、安全建模和验证流程，不规定运行时实现方式。
主要功能
- 01组织 API 文档与资源
- 02指导路径、操作和响应设计
- 03定义可复用模式与示例
- 04建模安全方案与作用域
- 05涵盖规范检查和破坏性变更检测
- 06区分契约设计与运行时实现
适用场景
- 01审查 OpenAPI 规范
- 02改进 API 模式与操作设计
- 03设置契约验证关卡
- 04明确契约中的安全要求
安装
复制下面的命令，在终端中运行。
$
npx skills add https:/安装后在 Claude Code 中输入/701-technologies-openapi确认已加载。
附带文件references/701-technologies-openapi.md
详细介绍
OpenAPI 3.x 最佳实践
帮助团队编写易于维护的 OpenAPI 3.x 契约，使其始终符合 HTTP 语义和使用者需求。
此技能涵盖哪些内容？
- 文档结构：
openapi、info、servers、tags，以及一致的资源分组 - 路径和操作设计：参数、请求体、响应矩阵、
operationId、状态码 - 可复用的
components（架构、参数、响应、安全方案）和示例 - 验证和 CI：规范 lint、破坏性变更检查、代码生成前的门禁
- 契约中的安全建模（方案、作用域、全局安全与操作级安全）
- 明确划分契约优先设计与运行时实现相关事项
**范围：**仅关注契约优先的质量。此技能应聚焦于 OpenAPI 设计、质量和治理指导。
约束
除非用户明确要求集成 Java 框架，否则建议应局限于 OpenAPI 层。编辑此仓库的 XML 源文件后，重新生成技能并验证构建。
- 强制要求：在同一变更集中提出 Java 或 Maven 变更前，运行
./mvnw compile或mvn compile - 框架：指导应以契约为中心；不要规定特定框架的控制器接线方式或运行时暴露细节
- 模糊测试：模糊测试指导应保持高层次并聚焦于契约，不要链接到外部技能标识符
- 验证：在提交变更前，运行
./mvnw clean verify或mvn clean verify - 边界情况：如果用户目标不明确，先停止操作并提出澄清问题，再编辑文件或运行项目范围的命令
- 边界情况：如果缺少必需的上下文、文件、凭据或工具，请明确说明阻碍，并询问用户是希望进行环境设置还是采用替代指导
- 边界情况：如果请求的变更与项目约束或安全边界冲突，请说明冲突，并请用户确认优先采用哪种权衡方案
何时使用此技能
- 审查 OpenAPI
- 改进 OpenAPI
- 改进 API 契约
- 改进 API 架构设计
- 验证 OpenAPI 规范
工作流
- 阅读参考资料并评估项目上下文
阅读 references/701-technologies-openapi.md，并检查当前的 API 和上下文资料，再提出变更建议。
- 确定范围并选择改进目标
明确预期结果、约束，以及要应用的最小安全变更集。
- 应用与技术相符的变更
按照参考资料中的模式和项目惯例，实现或重构相关资料。
- 运行验证并报告结果
执行适当的检查，并总结变更内容、已验证事项和后续操作。
参考资料
详细指导、示例和约束请参阅 references/701-technologies-openapi.md。
评论
支持 Markdown