OpenAPI 规范

用 OpenAPI 描述 HTTP 接口的路径、参数、模式与响应;描述文件可生成文档、客户端 SDK、服务端骨架与测试,是接口协作的通用载体。

片段

片段
openapi: 3.1.0
info: { title: Orders API, version: 1.0.0 }
paths:
  /orders/{id}:
    get:
      parameters:
        - { name: id, in: path, required: true, schema: { type: string } }
      responses:
        '200': { description: OK }
规范文件要与实现同步校验:用契约测试或网关校验防止“文档与实现两张皮”。

易错点

  • 规范文件长期未与实现同步,联调基于过时文档
  • 模式定义过细,客户端生成代码对新增字段脆弱

数据来源与参考

  • OpenAPI Specification 3.1(spec.openapis.org)
  • OpenAPI Initiative 文档
​‌‌​​‌​​​‌‌​‌‌‌‌​‌‌​​​‌‌​‌‌‌​​‌‌​​‌​‌‌‌​​‌‌‌​​​‌​‌‌​‌​​‌​‌‌‌​​​‌​‌‌​‌​​‌​‌‌​​​‌‌​‌‌‌​‌​​​‌‌​‌‌‌‌​​‌​‌‌‌​​‌‌​​​‌‌​‌‌​‌‌‌‌​‌‌​‌‌​‌