自定义

生成的 CLI 可以在三个层面进行自定义：构建所基于的 OpenAPI 规范、将多个规范组合为单一命令树的配置，以及在规范派生命令旁添加自定义命令的代码。

覆盖和 Overlays

CLI 生成器支持 overrides 和 overlays 两种方式来在构建 CLI 前自定义 OpenAPI 规范。这允许您添加 Fern 扩展、重命名参数或移除内部端点，而无需修改原始规范。

Overlays 遵循 OpenAPI Overlay 规范并使用 JSONPath 来定位元素：

1
overlay: 1.0.0
2
info:
3
  title: CLI customizations
4
  version: 1.0.0
5
actions:
6
  - target: $.paths['/plants'].get
7
    update:
8
      x-fern-sdk-group-name: plants
9
      x-fern-sdk-method-name: list
10
  - target: $.paths['/internal/debug']
11
    remove: true

当两者同时存在时，先应用 overrides，再应用 overlays。

多规范合并

单个 CLI 可以将多个 OpenAPI 规范合并为一个命令树。这对于将规范按域或版本拆分的 API 很有用。

规范可以平级合并（所有命令在顶层）或在命名空间前缀下合并：

1
CliApp::new("my-api")
2
    .spec(include_str!("core.yaml"))
3
    .spec_under("billing", include_str!("billing.yaml"))
4
    .run()

这生成的 CLI 中核心命令位于顶层，计费命令位于 billing 子命令下：

$
my-api users list          # 来自 core.yaml
$
my-api billing invoices list  # 来自 billing.yaml

当命名空间与传入规范中的顶级资源匹配时，CLI 会将该资源的方法提升到命名空间中以避免重复（例如 billing billing invoices list 变为 billing invoices list）。

自定义命令

生成的 CLI 可以在规范派生的命令旁包含自定义命令。自定义命令可以访问同一个 API 执行器，因此可以将多个 API 调用链接到单个工作流中。

1
CliApp::new("my-api")
2
    .spec(include_str!("openapi.yaml"))
3
    .auth_scheme_env("bearerAuth", "MY_API_TOKEN")
4
    .command(whoami_cmd(), whoami_handler)
5
    .run()