OpenAPI扩展

枚举描述、名称、大小写和可用性

以 Markdown 格式查看

OpenAPI 原生不支持为枚举值添加描述。要在 Fern 中实现此功能，您可以使用 x-fern-enum 扩展。

描述和可用性

使用 description 为单个枚举值添加文档，使用 deprecated 将值标记为已弃用而不会弃用整个枚举。这些设置会传播到生成的 SDK 和文档网站中。

openapi.yml
1components:
2  schemas:
3    CardSuit:
4      enum:
5        - clubs
6        - diamonds
7        - hearts
8        - spades
9      x-fern-enum:
10        clubs:
11          description: 梅花花色
12        diamonds:
13          description: "已弃用。请使用红心。"
14          deprecated: true
15        hearts:
16          description: 红心花色
17        spades:
18          description: 黑桃花色

自定义名称

使用 name 字段自定义生成代码中枚举值的名称。当枚举值依赖符号字符而可能导致生成的代码无法编译时，这特别有用。

例如，以下 OpenAPI：

openapi.yml
1components:
2  schemas:
3    Operand:
4      enum:
5        - '>'
6        - '<'
7      x-fern-enum:
8        '>':
9          name: GreaterThan
10          description: 检查值是否大于
11        '<':
12          name: LessThan
13          description: 检查值是否小于

将生成：

operand.ts
1export enum Operand {
2  GreaterThan = ">",
3  LessThan = "<"
4}

自定义大小写

使用 casing 字段为每个目标语言的命名约定指定确切的大小写。这比仅使用 name 提供了更精细的控制，后者只为生成的代码设置单个默认名称。

casing 字段支持四个可选的子字段：

  • snake — snake_case 的覆盖（用于 Python 等语言）
  • camel — camelCase 的覆盖（用于 TypeScript/Java 等语言）
  • screamingSnake — SCREAMING_SNAKE_CASE 的覆盖（用于 Go 等语言）
  • pascal — PascalCase 的覆盖（用于 C# 等语言）
openapi.yml
1components:
2  schemas:
3    Status:
4      type: string
5      enum:
6        - active
7        - in-progress
8      x-fern-enum:
9        active:
10          description: 项目处于活动状态
11        in-progress:
12          name: InProgress
13          casing:
14            snake: in_progress
15            camel: inProgress
16            screamingSnake: IN_PROGRESS
17            pascal: InProgress

您可以将 casing 与 name 一起使用。name 字段设置默认生成的名称，而 casing 提供按语言的覆盖。如果两者都指定，casing 值对其各自的语言目标具有优先级。