OpenAPI
翻译 OpenAPI 3.x YAML 中的说明性字段,同时保持路径、操作标识符和引用不变。
OpenAPI 文档既包含机器可读的 API 契约,也提供面向使用者的说明。yaml-openapi 文件处理器根据字段在 OpenAPI 3.x YAML 中的位置,选取 title、description 和 summary 字段。路径、操作 ID 和引用保持不变。
保持 API 契约稳定 #
在以下示例中,操作标识保持不变,说明则可以翻译为其他语言:
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、引用、必填字段和模式值。然后结合契约阅读渲染后的描述。即使规范本身仍然有效,响应描述中条件或承诺的变化也可能误导开发者。