OpenAPI 扩展 | Fern Documentation

抢先体验

CLI 生成器处于抢先体验阶段。联系我们开始使用。

CLI 生成器读取多个 Fern OpenAPI 扩展来塑造生成的 CLI。您可以直接在规范中添加这些扩展，也可以通过 overlays 应用。

命令结构

`x-fern-sdk-group-name`

决定子命令分组层级。列表中的每个元素成为一个嵌套子命令，名称从 camelCase 转换为 kebab-case。

openapi.yml

1 paths:
2   /scheduled-events/{uuid}/invitees:
3     get:
4       x-fern-sdk-group-name:
5         - scheduledEvents
6         - invitees
7       x-fern-sdk-method-name: list-event-invitees

生成：cli scheduled-events invitees list-event-invitees

`x-fern-sdk-method-name`

设置叶子命令名称（按原样使用）。

openapi.yml

1 paths:
2   /users/me:
3     get:
4       x-fern-sdk-method-name: get-current-user

生成：cli get-current-user（如果同时设置了 x-fern-sdk-group-name，则嵌套在分组下）。

如果两个扩展都未设置，CLI 回退到 operationId。

参见 SDK 方法名称了解更多详情。

过滤

`x-fern-ignore`

从生成的 CLI 中排除操作或参数。被忽略的操作不生成命令；被忽略的参数不生成标志。

openapi.yml

1 paths:
2   /internal/debug:
3     get:
4       x-fern-ignore: true

参数级别：

openapi.yml

1 paths:
2   /users:
3     get:
4       parameters:
5         - name: internalParam
6           in: query
7           x-fern-ignore: true
8           schema:
9             type: string

参见忽略元素了解更多详情。

可用性徽章

`x-fern-availability`

在 --help 输出中的命令旁添加状态徽章。

值	徽章
`alpha`	`[Alpha]`
`beta`	`[Beta]`
`preview`	`[Preview]`
`generally-available` 或 `ga`	`[GA]`
`deprecated`	`[Deprecated]`
`legacy`	`[Legacy]`

openapi.yml

1 paths:
2   /v2/reports:
3     get:
4       x-fern-availability: beta

OpenAPI 的标准 deprecated: true 也会被识别，在未设置 x-fern-availability 时映射为 [Deprecated]。

参见可用性了解更多详情。

参数命名

`x-fern-parameter-name`

覆盖从参数派生的 CLI 标志名称。默认情况下，参数名称转换为 kebab-case 作为标志使用。

openapi.yml

1 paths:
2   /users:
3     get:
4       parameters:
5         - name: X-API-Version
6           in: header
7           schema:
8             type: string
9           x-fern-parameter-name: api-version

生成 --api-version 而非 --x-api-version。

参见自定义参数名称了解更多详情。

分页

`x-fern-pagination`

为端点启用自动分页。存在时，CLI 为该命令识别 --page-all、--page-limit 和 --page-delay 标志。

openapi.yml

1 paths:
2   /plants:
3     get:
4       operationId: list_plants
5       x-fern-pagination:
6         cursor: $request.cursor
7         next_cursor: $response.next
8         results: $response.results

参见分页了解所有支持的分页方案（offset、cursor、URI 和 path）。