OpenAPI 规范：设计第一的 API 开发

yaml openapi: 3.1.0 info: title: 宠物店 API version: 1.0.0 description: 一个管理宠物和用户的示例 API paths: /pets: get: summary: 获取所有宠物 operationId: listPets responses: '200': description: 宠物列表 content: application/json: schema: type: array items: $ref: '#/components/schemas/Pet' components: schemas: Pet: type: object required: - id - name properties: id: type: integer format: int64 name: type: string tag: type: string

#### 文档元数据与版本
- `openapi`: 指定使用的 OAS 版本，3.1.0 是最新稳定版。
- `info`: 提供 API 的名称、版本、描述、联系方式等信息，这是文档呈现给使用者的第一印象。

#### 路径与操作：定义 API 端点
`paths` 部分是 API 的核心。每个路径（如 `/pets`）对应一个端点，其下可定义 HTTP 方法：
- `get`, `post`, `put`, `delete` 等。
- 每个操作可包含 `summary`（简短说明）、`operationId`（唯一标识，用于代码生成）、`parameters`（查询参数、路径参数等）、`requestBody`（请求体）和 `responses`。

在上面的例子中，`GET /pets` 返回一个宠物对象数组，其结构由 `$ref` 引用到组件中。

#### 组件与复用：避免重复
`components` 对象是管理可复用片段的仓库，你可以定义：
- `schemas`: 数据模型
- `parameters`: 可重用的参数
- `responses`: 可重用的响应
- `examples`: 请求/响应示例
- `securitySchemes`: 认证定义

使用 `$ref` 可以引用这些组件，例如 `#/components/schemas/Pet`。这让规范保持 DRY（Don't Repeat Yourself）且易于维护。

### 核心建模：请求、响应与数据校验

#### 描述请求参数
路径参数、查询参数和头参数都在 `parameters` 中定义。每个参数需指明 `name`、`in`（query、path、header）、`required`（布尔值）及 `schema`。示例：

```yaml
parameters:
  - name: petId
    in: path
    required: true
    schema:
      type: integer
      format: int64
  - name: limit
    in: query
    schema:
      type: integer
      maximum: 100
      default: 20

定义请求体

当需要客户端发送数据时，使用 requestBody。它包含 content 字段，描述媒体类型（如 application/json）以及对应的 schema。可以标记 required: true。

构建响应

每个响应状态码作为一个键，必须包含 description。对于返回数据的响应，指定 content。你也可以为常见状态码创建可复用的响应组件。

数据校验与 JSON Schema

OpenAPI 3.1 完全兼容 JSON Schema 2020-12，这意味着你可以使用所有 JSON Schema 的验证关键字：type, required, enum, minimum, pattern（正则），甚至可以通过 oneOf, anyOf 组合模式。这有助于自动生成精确的客户端校验逻辑。

认证与安全定义

通过 components/securitySchemes 声明 API 支持的认证方式，然后在全局或操作级别应用 security。常见的方案包括：

• apiKey: 通过 header 或 query 传递的 token。
• http 类型中的 bearer (JWT) 和 basic（不推荐）。
• oauth2 与 openIdConnect。

components:
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT
security:
  - bearerAuth: []