定义
Swagger 是基于 OpenAPI 规范的 API 文档与测试工具套件，提供可读的 API 描述、交互式文档与在线调试能力。在国际物联网云平台（ICMP）中，Swagger 便于开发者理解与集成 RESTful API，降低对接 API Gateway 的门槛，与 SDK 配合加速客户系统集成。
工作原理
Swagger 使用 OpenAPI（原 Swagger 规范）YAML/JSON 格式描述 API：端点、方法、参数、请求/响应结构、鉴权方式等。Swagger UI 将规范渲染为可读文档，支持「Try it out」在线调用，开发者无需离开浏览器即可测试 API。规范还可用于自动生成 SDK、Mock 服务、API Gateway 配置等。ICMP 的 RESTful API 通常提供 Swagger 文档，与 OAuth2、API Key 鉴权说明一并展示。
应用场景
典型场景包括：开发者集成——客户开发人员通过 Swagger 文档理解 API 能力，在线调试后集成至自有系统；POC 与试点——在 POC 阶段快速验证 API 功能与参数；Reseller 对接——渠道商技术团队通过 Swagger 将 ICMP 能力集成至 Partner Portal；内部协作——前后端、多团队基于统一规范协作，减少沟通成本。结合 Audit Trail，API 调用可追溯，支撑问题排查与合规审计。
在 ICMP 中的实践
达希物联 ICMP 的 RESTful API 提供完整的 Swagger/OpenAPI 文档，覆盖 SIM 管理、用量查询、计费、PLMN Selection、Event Subscription 等能力。文档与 API Gateway 同步更新，支持 OAuth2 与 API Key 的鉴权说明与在线授权。开发者可基于规范生成多语言 SDK，或直接使用文档进行集成。结合 TLS 加密与 IAM 鉴权，保障文档与 API 访问的安全合规。