定义
OpenAPI（原 Swagger）是描述 RESTful API 的开放规范，定义接口路径、参数、响应格式等。设备管理平台提供 OpenAPI 文档，便于第三方系统集成设备管理、数据查询、OTA 等能力，与 RESTful API 配套使用。
规范内容与工具链
OpenAPI 3.x 使用 YAML/JSON 描述 API 的路径、方法、请求/响应 Schema、鉴权方式等。基于规范可自动生成交互式文档（Swagger UI）、客户端 SDK、服务端桩代码及 Mock 服务。设备管理平台通常为设备 CRUD、产品管理、OTA 任务、告警订阅、数据查询等接口提供 OpenAPI 定义；支持版本管理（如 /v1、/v2），便于 API 演进与兼容。
与 DMP 的集成
平台通过 OpenAPI 文档降低集成门槛，第三方可通过文档理解接口、生成代码、进行联调。与 Webhook 回调、Event Stream 事件流等能力配合，可构建完整的集成生态。文档可托管于平台或导出供离线使用；支持 Try it out 在线调试，提升开发者体验。API 网关可基于 OpenAPI 进行请求校验、限流与监控。
应用场景
适用于系统集成、自动化运维、第三方应用开发、BI 工具对接等。OpenAPI 是设备管理平台开放能力的标准载体，有助于构建合作伙伴生态与加速业务集成。
接口描述和运行时网关
OpenAPI 是一份对接口的结构化描述：有哪些路径、用什么方法、参数和请求体是什么形状、成功和失败时返回什么、调用者要怎样证明身份。人或工具读这份描述来生成说明、客户端和模拟服务。它本身不是网关，也不会在运行时自动拒绝不符合文档的请求，除非网关或服务被配置成按这份描述做校验。因此文档写得完整，只说明意图被记录下来；线上是否照做，要靠实现和校验。版本应写在描述和路径里，旧版本的行为变化不能只改文字不改版本。设备管理相关的接口，例如查询某台设备、创建升级任务、订阅告警，应在描述里写明标识从哪里来、哪些字段只读、分页如何继续。示例要用明显的占位值，不能把真实密钥放进仓库。空中升级任务的创建参数若在描述里是可选、在服务里是必填，集成方会在联调时才发现。遥测查询若没有写明时间范围的上限，调用方可能一次拉出超出接口设计的数据量。
文档可以当成契约的条件
描述要能当契约，需要和当前部署的版本一一对应，并且由同一变更流程更新：接口改了，描述一起改，旧描述仍能取到。鉴权方式、错误码、幂等和频率限制都属于契约，只写路径和成功示例是不够的。破坏兼容的改动应进入新版本，而不是在原路径上改变字段含义。生成的客户端若被提交进业务系统，应记录它对应哪一版描述，避免描述已经升级、客户端仍按旧字段解析。试调用功能使用的账号权限要小，并与生产数据隔离。对合作方公开的描述应去掉内部字段。服务端若按描述校验入参，校验规则要和文档同步发布，不能文档写枚举、服务接受任意字符串，或相反。多团队维护时，要有人负责这份描述的合并，避免并行分支各写各的路径。
文档版本和线上路径脱节
描述停留在初版，线上已经增加必填参数，调用方按文档会得到含糊的失败。同一路径在描述里是一个资源，在线上被网关改写成另一个服务，字段名对不上。错误码只在内部维基里维护，文档把所有失败都写成一个通用对象，调用方无法分支处理。安全方案在文档里写成一种令牌，线上已改为另一种，示例却仍能“试通”因为试调用环境没更新。把描述文件手改后不经校验，缩进或引用错误，生成的客户端缺了一半接口。版本号只写在文件名上，正文里的服务器地址仍指向旧环境。废弃路径没有在描述里标记，新集成还在使用即将关闭的接口。文档仓库和运行配置分属两人，发布当天忘记一起更新，联调结论变成“平台不稳定”，其实是契约没有一起发布。