从 JSON 样例推导 OpenAPI Schema

写接口文档最头疼的是手敲 schema。有返回值样例，先生成 JSON Schema，再嵌进 OpenAPI 即可。

更新于 2026-08-30 · 阅读约 3 分钟

怎么嵌

把工具生成的 Schema 作为 schema 字段放进 OpenAPI 的响应或请求体里：

paths:
  /users:
    get:
      responses:
        "200":
          description: 用户列表
          content:
            application/json:
              schema:
                type: array
                items:
                  type: object
                  properties:
                    id: { type: integer }
                    name: { type: string }
                  required: [id, name]

为什么这么做

• 文档和真实返回值对得上，Swagger UI 能直接示例。
• 前端用 OpenAPI 生成 SDK 时，类型直接来自这份 schema。
• 比纯文字描述更不易过时。

提醒

示例只代表一条数据。分页、空数组、错误结构最好各生成一份再合并，别只贴成功样例。

👉 打开工具，把接口返回值生成 Schema 再贴进 OpenAPI