v0.12.0 — 枚举值表补逐值中文说明

枚举值表补逐值中文说明

枚举值表原来只有两列，取值是英文标识，读者得回上面的字段描述里翻一遍才知道哪个是哪个：

枚举值
| 字段                | 取值         |
| data.attacks[].kind | thunder_hit  |
| data.attacks[].kind | thunder_block|
| data.attacks[].kind | steal        |

现在读 spec 的 x-enumDescriptions 把表升成三列：

枚举值
| 字段                | 取值          | 说明                          |
| data.attacks[].kind | thunder_hit   | 建筑被雷击损毁                 |
| data.attacks[].kind | thunder_block | 被御守挡下，建筑无损           |
| data.attacks[].kind | steal         | 被偷金币                       |

OpenAPI 没有标准字段描述单个枚举值，x-enumDescriptions 是社区通行的扩展键（{取值: 说明}），连字符写法 x-enum-descriptions 也认。

spec 侧怎么产出

zod 4 直接用 .meta()，chanfana 会原样透传（实测可用）：

kind: z
  .enum(["thunder_hit", "thunder_block", "steal"])
  .describe("对抗类型")
  .meta({
    "x-enumDescriptions": {
      thunder_hit: "建筑被雷击损毁",
      thunder_block: "被御守挡下，建筑无损",
      steal: "被偷金币",
    },
  }),

.describe() 和 .meta() 谁先谁后都不会互相覆盖。

边界

按「宁可不写，也不写错」处理：

• 只配了部分取值 → 缺的那格留空，不错位
• 整张表都没配 → 保持两列，不留空列
• 说明值不是非空字符串 → 忽略，免得把 [object Object] 写进文档

更新

npm i -g https://github.com/leeguooooo/openapi-lark/releases/latest/download/openapi-lark.tgz

升级后首次 sync 因版本号纳入 hash 会全量重推一次，带枚举表的接口文档会一并更新。