---

title: OpenAPI 3.1 合约驱动开发与客户端生成指南

keywords:

• OpenAPI 3.1
• 合约驱动
• 代码生成
• typescript-fetch
• schema

description: 使用 OpenAPI 3.1 规范进行合约驱动设计，并通过生成工具产出客户端与文档，覆盖版本与兼容要点。

categories:

• 文章资讯
• 技术教程

---

OpenAPI 3.1 合约驱动开发与客户端生成指南

规范片段

openapi: 3.1.0
info:
  title: Sample API
  version: 1.0.0
paths:
  /items/{id}:
    get:
      parameters:
        - name: id
          in: path
          required: true
          schema: { type: string }
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Item'
components:
  schemas:
    Item:
      type: object
      properties:
        id: { type: string }
        name: { type: string }

生成示例

openapi-generator-cli generate -i openapi.yaml -g typescript-fetch -o client

要点

• 保持响应类型与错误模型一致
• 使用语义化版本管理合约演进

总结

在合约驱动模式下，OpenAPI 结合生成工具可提升跨端协作效率与一致性。