OpenAPI

翻译 OpenAPI 3.x YAML 中的说明性字段,同时保持路径、操作标识符和引用不变。

OpenAPI 文档既包含机器可读的 API 契约,也提供面向使用者的说明。yaml-openapi 文件处理器根据字段在 OpenAPI 3.x YAML 中的位置,选取 title、description 和 summary 字段。路径、操作 ID 和引用保持不变。

保持 API 契约稳定 #

在以下示例中,操作标识保持不变,说明则可以翻译为其他语言:

yaml
openapi: 3.0.3
info:
  title: Order service
  version: 1.0.0
paths:
  /orders:
    get:
      operationId: listOrders
      summary: List your orders
      responses:
        "200":
          description: Orders retrieved

处理器会选取标题、摘要和响应描述。/orders、listOrders 和 1.0.0 保持不变。选取范围还包括信息字段、标签和外部文档的描述、路径描述,以及可识别的模式容器和操作容器中的描述性字段。

请检查这些容器中以对象为值的示例和默认值。名为 title、description 或 summary 的嵌套属性也可能被选中,即使它属于示例载荷数据。其他模式值(如普通枚举字符串和 $ref 值)保持不变。

解析器要求文档采用 YAML 映射结构,且 openapi 版本以 3. 开头。Swagger 2.x、未指定版本的文档以及其他版本均不受支持。即使 OpenAPI 允许使用 JSON,此处理器也不会因此选取 JSON 格式的 OpenAPI 文件;它约定处理的是 YAML 格式。

重建与复用 #

规范树由当前源文档定义。现有文本根据描述性字段的标识及其出现情况进行匹配,操作标识也会用于辅助对齐。源描述发生变化时,需要重新翻译;未发生变化且匹配的字段则可以复用目标文本。

YAML 序列化器会重建文档,并可能对格式进行规范化处理。请确保之前的源规范与目标规范保持对齐,并检查是否有字段移动或描述重复的情况影响复用。

选择规范处理器 #

在 CLI 文件配置中,为 .yaml 或 .yml 明确指定 yaml-openapi。仅凭扩展名无法区分 API 规范与应用文本目录。通用 YAML 处理器会选取多得多的字符串;以语言区域为根的 YAML 则采用不同的外层结构约定。

通过 CLI 配置或 GitHub 选择文件并设置目标路径。OpenAPI 不支持在 CLI 中按键限定翻译范围。

验证契约并阅读描述 #

使用 OpenAPI 工具验证重建后的文档,并对照源文档检查路径、操作 ID、引用、必填字段和模式值。然后结合契约阅读渲染后的描述。即使规范本身仍然有效,响应描述中条件或承诺的变化也可能误导开发者。