API 生成：从描述到接口

API 生成根据自然语言或示例描述产出接口定义、请求体、响应结构与路由骨架，常见输出为 OpenAPI 或具体框架代码。它让前后端先对齐契约，再各自实现。

它是什么

模型读取「一个创建用户的接口，返回 201 与用户 ID」这类描述，生成路径、方法、参数校验与样例响应，甚至可直接落到 FastAPI、Express 等代码。输出应视为契约草案。

为什么要生成

• 前后端先对齐契约，再各自实现，减少返工与误解。
• 自动产出 OpenAPI 文档，保证代码与文档一致。
• 快速搭建原型路由，聚焦业务逻辑而非样板。
• 让接口设计可被评审，而非藏在实现里。

怎么生成

用描述驱动模型输出 OpenAPI 片段，并明确字段类型与必填项。

paths:
  /users:
    post:
      summary: 创建用户
      requestBody:
        content:
          application/json:
            schema:
              type: object
              required: [name, email]
              properties:
                name: { type: string }
                email: { type: string }
      responses:
        "201":
          description: 创建成功

注意点

• 生成的契约要补充鉴权、限流与错误码，模型常省略这些关键项。

• 校验字段类型与必填项符合真实业务规则，而非随意设定。

• 不要暴露内部字段（如密码哈希）到响应中。

• 让契约先于实现落地，并把版本纳入管理。

• 为错误响应定义统一结构，便于前端一致处理。

• 给接口加版本前缀，避免破坏性变更影响旧客户端。

• 在契约中写明速率限制与配额，管理调用方预期。

小结

API 生成从描述产出接口契约与骨架，利于前后端对齐与文档同步；但鉴权、限流、错误模型与敏感字段仍需人工补全，并在评审中固化。

参考与延伸阅读

• OpenAPI 规范官方文档。已核验。https://spec.openapis.org/oas/latest.html
• FastAPI 官方文档。已核验。https://fastapi.tiangolo.com/