SwaggerHub 连接器

需要解决的具体问题

在 API 治理与文档协作场景中，团队常需快速获取 SwaggerHub 中的 API 定义、版本列表、项目结构及注册表元数据。手动操作不仅耗时，还易因参数配置错误导致数据不一致。当需要批量拉取多个 API 的模板版本或跨所有者搜索注册表项时，传统界面操作难以满足自动化与可复现的需求。

技能如何工作

核心能力与关键步骤

• 14 个专用动作：覆盖 SwaggerHub 资源的读取与搜索操作，包括 get_api_definition、list_api_versions、search_registry_specs 等。所有动作通过 oo CLI 调用连接器实现，无需在本地管理 API 密钥。
• 契约驱动执行：执行前建议先通过 oo connector schema 获取当前动作的输入/输出契约，确保构造的 JSON payload 符合规范。响应统一包含 data 与 meta.executionId，便于追溯执行记录。
• 安全分级执行：读取类动作（get/list/search）可直接运行；涉及状态变更的操作（如未来扩展的创建、更新类动作）需在运行前与用户确认具体 payload 及影响范围。

适用边界与注意点

• 凭据托管：SwaggerHub 连接凭据由 OOMOL 服务端注入，本地无需处理 API Key 等敏感信息。首次使用需确保 oo CLI 已安装、登录并完成 SwaggerHub 连接（认证类型：API Key），但无需手动执行登录或连接流程。
• 错误处理：若遇 scope_missing、credential_expired 等错误，说明连接状态异常，需重新建立 SwaggerHub 连接；遇到 HTTP 402 时需检查 OOMOL 账户余额。
• 只读优先：当前版本聚焦于 SwaggerHub 资源的读取与检索场景，未提供修改或删除类操作，适合文档同步、版本审计、注册表盘点等非破坏性场景。