2. 接口调试基础概念：API 定义、RESTful 与 SOAP 对比、Swagger 阅读方法

在供应链计划系统的实时同步场景中，接口（API）是系统之间交换服务水平数据、库存状态与订单变更的唯一通道。理解 API 的本质、协议选型以及文档阅读方法，是进行接口调试的前提。

2.1 接口（API）的定义与核心要素

API（Application Programming Interface，应用程序编程接口）是一组预先定义的函数或协议，允许不同软件系统之间相互通信、请求数据或执行操作。在供应链计划系统中，API 通常用于：

• 数据查询：获取实时库存、在途订单、供应商产能。
• 数据提交：上传预测数据、创建补货建议。
• 状态同步：推送订单状态变更、服务水平指标更新。

2.2 RESTful 与 SOAP 协议对比

供应链计划系统集成中，RESTful 和 SOAP 是两种主流的 Web 服务协议。RESTful 基于 HTTP 原生语义，轻量灵活；SOAP 基于 XML 消息格式，强调安全与事务完整性。以下从多个维度进行对比：

2.3 接口文档阅读方法（Swagger / OpenAPI）

Swagger（现为 OpenAPI 规范）是 RESTful API 最广泛使用的文档标准。一份规范的 Swagger 文档包含以下核心区块：

• Info 对象：API 标题、版本、描述、联系人。
• Paths 对象：每个端点的 URL、方法、参数、请求体、响应结构。
• Components 对象：复用的数据模型（Schema）、安全方案。
• Servers 对象：基础 URL（如 https://api.scm.com/v2）。

阅读接口文档时，建议按以下步骤进行：

1. 确认基础路径：找到 servers.url，这是所有请求的前缀。
2. 定位目标端点：在 paths 中按业务关键词搜索（如 /inventory、/orders）。
3. 检查请求方法：GET 用于查询，POST 用于创建，PUT 用于全量更新，PATCH 用于部分更新。
4. 查看参数定义：区分 query（查询参数）、path（路径参数）、header（请求头参数）。
5. 理解响应结构：关注 200 成功响应中的 schema，确认字段类型与必填性。

2.4 接口文档实战：读取一个库存查询接口

以下是一个简化的 Swagger 文档片段，对应供应链计划系统中查询实时库存的接口。请结合上述阅读方法进行解析：

openapi: 3.0.0
info:
  title: 供应链计划系统 - 库存服务
  version: 1.0.0
servers:
  - url: https://api.scm.example.com/v2
paths:
  /inventory/{sku}:
    get:
      summary: 按 SKU 查询实时库存
      parameters:
        - name: sku
          in: path
          required: true
          schema:
            type: string
        - name: warehouse
          in: query
          required: false
          schema:
            type: string
      responses:
        '200':
          description: 成功返回库存数据
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/InventoryResponse'
components:
  schemas:
    InventoryResponse:
      type: object
      properties:
        sku:
          type: string
        quantity:
          type: integer
        warehouse:
          type: string
        lastUpdated:
          type: string
          format: date-time