generators.yml 配置模式

The name of the HTTP header to use for authentication.

A descriptive name for this authentication scheme.

The type of the header value.

A prefix to prepend to the header value (e.g., "Bearer " or "Token ").

Environment variable name containing the authentication value. When specified, the generated SDK will automatically scan for this environment variable at initialization.

Must be set to "basic" for Basic authentication schemes.

Configuration for the username credential.

Custom parameter name for the username in the generated SDK. If not specified, defaults to "username". Use this to provide more descriptive or domain-specific parameter names like "clientId", "userEmail", or "merchantId".

Configuration for the password credential.

Custom parameter name for the password in the generated SDK. If not specified, defaults to "password". Use this to provide more descriptive or domain-specific parameter names like "clientSecret", "apiKey", or "merchantKey".

Environment variable name that the SDK will automatically scan for the username or password value. When this environment variable is present, users don’t need to explicitly provide the username parameter. Follow naming conventions like YOUR_APP_USERNAME or SERVICE_CLIENT_ID.

Use when your API expects only one half of the basic auth credential pair. When true, the field is removed from the generated SDK’s public API. The omitted field is treated as an empty string when encoding the Authorization header (omitting password produces base64("username:"); omitting username produces base64(":password")). When both are omitted, the Authorization header is skipped entirely.

Must be set to "bearer" for Bearer token authentication schemes.

Configuration for the bearer token.

A descriptive name for the token.

Environment variable name containing the bearer token. When specified, the generated SDK will automatically scan for this environment variable at initialization.

Must be set to "oauth" for OAuth authentication schemes.

The OAuth 2.0 grant type. Currently only "client-credentials" is supported.

OAuth scopes to request when obtaining access tokens (e.g., "read:users", "write:orders").

Environment variable name containing the OAuth client ID. When specified, the generated SDK will automatically scan for this environment variable at initialization.

Environment variable name containing the OAuth client secret. When specified, the generated SDK will automatically scan for this environment variable at initialization.

Prefix added to the access token in the Authorization header (e.g., "Bearer" results in "Authorization: Bearer <token>"). Useful when your API expects a custom format.

HTTP header name used to send the access token. Defaults to "Authorization" but can be customized if your API uses a different header (e.g., "X-API-Token").

The endpoint that issues access tokens, such as 'auth.get_token' or 'POST /oauth/token'. If your API uses namespaces, prefix with the namespace and :: (e.g., 'payments::POST /oauth/token').

Maps OAuth parameter names to your API’s request field names. Use this when your token endpoint expects different field names than the OAuth standard (e.g., your API uses clientId instead of client_id).

The request field name for the client ID in your API (e.g., "clientId", "client_id").

The request field name for the client secret in your API (e.g., "clientSecret", "client_secret").

The request field name for scopes in your API (e.g., "scope", "scopes").

Maps your API’s response field names to OAuth standard names. Use this when your API returns tokens with different field names (e.g., accessToken instead of access_token).

The response field name for the access token in your API (e.g., "accessToken", "access_token").

The response field name for token expiration time in seconds (e.g., "expiresIn", "expires_in"). When present, the SDK automatically refreshes tokens before expiration.

The response field name for the refresh token in your API (e.g., "refreshToken", "refresh_token"). Required if using the refresh-token flow.

The endpoint that refreshes access tokens (e.g., "POST /oauth/refresh" or "auth.refreshToken"). If your API uses namespaces, prefix with the namespace and :: (e.g., "payments::POST /oauth/refresh").

Maps OAuth parameter names to your API’s request field names for the refresh flow.

The request field name for the refresh token in your API (e.g., "refreshToken", "refresh_token").

Maps your API’s refresh response field names to OAuth standard names.

The response field name for the new access token (e.g., "accessToken", "access_token").

The response field name for the new token’s expiration time in seconds (e.g., "expiresIn", "expires_in").

The response field name if your API issues a new refresh token with each refresh (token rotation).

OpenAPI 规范文件的路径。

用于拉取更新的 API 定义源 URL。有关如何设置自动同步的说明，请参阅 同步您的 OpenAPI 规范。

OpenAPI Overlay 文件的路径。Overlay 遵循 OpenAPI Overlay 规范，是自定义 OpenAPI 规范的推荐方法。

OpenAPI 覆盖 文件的路径，或按顺序应用的多个覆盖文件路径列表。建议使用 overlays 来实现基于标准的方法。

1
# 单个覆盖文件
2
overrides: ./overrides.yml
3
4
# 多个覆盖文件（按顺序应用）
5
overrides:
6
  - ./base-overrides.yml
7
  - ./sdk-overrides.yml

规范的命名空间。用于配置 包含多个 API 版本的单个包。

此单独规范的 OpenAPI 特定生成设置。要在所有 OpenAPI 规范中应用相同的设置，请改用全局 api.settings。

是否将 OpenAPI 定义中模式的标题用作 Fern 中类型的名称。

是否在生成的内联请求中包含路径参数。

是否在代码生成期间内联 allOf 模式。当为 true 时，Fern 递归访问 allOf 模式定义并将它们内联到子模式中。当为 false 时，allOf 模式通过继承进行扩展。

启用此设置允许子模式覆盖父属性要求。例如，子模式可以将父级的必需属性标记为可选。如果没有此设置，Fern 会忽略子模式的可选声明，而是保留父模式的要求。

是否首选包含字面量的无区别联合。

是否仅在生成的 SDK 中包含由端点引用的模式（树摇动）。

保留 API 定义设置中的可空模式。当为 false 时，可空模式被视为可选。

启用解析深层对象查询参数。

控制是否将对可空模式的引用包装在可选类型中。当为 false 时，可空引用被视为可以为 null 的必需字段。

控制在代码生成期间是否将可选模式强制转换为可空类型。当为 false 时，可选和可空被视为不同的概念。

启用在 OpenAPI 规范中探索只读模式。

启用在 OpenAPI 规范中遵循前向兼容枚举。

启用对二进制响应使用 bytes 类型。默认为文件流。

表单参数的默认编码。选项：form、json。

配置当模式中没有明确定义时，additionalProperties 应默认为什么。

如果为 true，将格式为 date 的字符串转换为字符串。如果为 false，转换为日期。

如果为 true，保留具有单个模式的 oneOf 结构。如果为 false，展开它们。

应用于 OpenAPI 规范的过滤器。使用此功能来限制生成的 SDK 或 API 参考文档中包含的端点 基于其路径。

如需基于标签的过滤而非基于路径的过滤，请在 group 级别使用 audiences。

要包含在生成的 SDK 中的端点。以 METHOD /path 格式指定端点（例如，POST /users、GET /users/{id}）。只有列出的端点才会包含在生成的 SDK 中；所有其他端点将被排除。如果您的 API 使用 命名空间，请使用命名空间和 :: 前缀（例如，payments::POST /users）。

控制为可选属性生成示例的最大深度。深度为 0 意味着不会为任何可选属性生成示例。

控制在响应中为可选属性生成示例的最大深度。

控制在代码生成期间是否将枚举转换为字面量类型。当为 false（默认值）时，枚举作为枚举类型保留，维护 OpenAPI 规范中的原始枚举结构。当为 true 时，枚举被强制转换为字面量类型，这对于生成的代码中更简单的类型表示很有用。

控制自动生成的请求名称的命名约定。启用时，在请求名称中将动词置于名词之前（例如，UsersListRequest 变为 ListUsersRequest），遵循更符合习惯的命名模式。

内联类型别名以简化生成的 SDK。启用时，通过直接用其底层类型替换简单别名来减少不必要的类型定义。对于具有许多基本类型或简单类型别名的 OpenAPI 规范很有用。

设置为 true 以内联所有别名，或使用带有 except 数组的对象来保留特定的类型别名：

1
settings:
2
  # 内联所有别名
3
  resolve-aliases: true
4
5
  # 或保留特定别名
6
  resolve-aliases:
7
    except:
8
      - UserId
9
      - OrganizationId

启用时，按主机将服务器分组到统一环境中，使具有多种协议（REST、WebSocket 等）的 API 能够共享环境配置。环境 URL ID 使用服务器名称，仅在需要解决冲突时添加路径或协议后缀。

AsyncAPI 规范文件的路径。

用于拉取更新的 API 定义源的 URL。

AsyncAPI 覆盖文件的路径，或多个顺序应用的覆盖文件的路径列表。

1
# 单个覆盖文件
2
overrides: ./asyncapi-overrides.yml
3
4
# 多个覆盖文件（按顺序应用）
5
overrides:
6
  - ./base-overrides.yml
7
  - ./sdk-overrides.yml

规范的命名空间。对于配置具有多个 API 版本的单个包很有用。

此单个规范的 AsyncAPI 特定生成设置。要在所有 AsyncAPI 规范中应用相同的设置，请改用全局 api.settings。

用于 AsyncAPI 消息的消息命名版本。选项：v1、v2。

是否使用 AsyncAPI 定义中模式的标题作为 Fern 中类型的名称。

在 API 定义设置中保留可空模式。当为 false 时，可空模式被视为可选的。

控制自动生成的请求名称的命名约定。启用时，在请求名称中将动词放在名词之前（例如，UsersListRequest 变为 ListUsersRequest），遵循更惯用的命名模式。

控制是否将对可空模式的引用包装在可选类型中。当为 false 时，可空引用被视为可以为 null 的必需字段。

控制在代码生成期间是否将可选模式强制转换为可空类型。当为 false 时，可选和可空被视为不同的概念。

启用时，将按主机将服务器分组到统一环境中，使具有多种协议（REST、WebSocket 等）的 API 能够共享环境配置。环境 URL ID 使用服务器名称，仅在需要解决冲突时才添加路径或协议后缀。

到 .proto 目录根目录的路径（例如 proto）。必须指定到包开始的位置。例如，如果您的包是 package.test.v1，文件路径为 protos/package/test/v1/test_file.proto，那么根目录应该是 protos/

到目标 .proto 文件的路径（例如 proto/user/v1/user.proto）。省略此参数将为整个根文件夹生成文档。

重写配置文件的路径，或者按顺序应用的多个重写文件的路径列表。仅用于 SDK 生成，不用于文档生成。

1
# 单个重写文件
2
overrides: ./overrides.yml
3
4
# 多个重写文件（按顺序应用）
5
overrides:
6
  - ./base-overrides.yml
7
  - ./sdk-overrides.yml

是否在本地编译 .proto 文件。默认使用远程生成（false）。启用时，您必须在您的机器上或在您的 CI/CD 环境（例如 GitHub Actions） 中安装 buf。

OpenRPC 规范文件的路径。

OpenRPC 覆盖文件的路径，或多个顺序应用的覆盖文件的路径列表。

1
# 单个覆盖文件
2
overrides: ./overrides.yml
3
4
# 多个覆盖文件（按顺序应用）
5
overrides:
6
  - ./base-overrides.yml
7
  - ./sdk-overrides.yml

规范的命名空间。

Conjure 规范文件的路径。

HTTP method of the default endpoint (e.g., GET, POST, PUT, DELETE).

Endpoint path for the default example (e.g., /users, /auth/login).

Whether the endpoint is a streaming endpoint. Defaults to false.

The title of the custom section as it will appear in the README.

The target SDK language for this section. The custom section will only appear in README files generated for the specified language.

The Markdown content of the custom section. You can use template variables in the format {{ variable }} that will be dynamically replaced with values specific to each SDK language when the README is generated.

Available template variables by language:

设置为 “npm” 进行 NPM 发布

自定义 NPM 注册表 URL

NPM 包名称（例如，“@myorg/api-sdk”）

用于发布的 NPM 认证令牌

设置为 “maven” 进行 Maven 发布

Maven 仓库 URL（可选，默认为 Maven Central）

“groupId:artifactId” 格式的 Maven 工件坐标

仓库身份验证用户名

仓库身份验证密码

用于包签名的 GPG 签名配置

用于包签名的 GPG 密钥 ID

GPG 密钥密码

GPG 密钥内容

设置为 “pypi” 进行 PyPI 发布

自定义 PyPI 注册表 URL（可选，默认为 PyPI）

Python 包名称（例如，“myorg-api-sdk”）

用于发布的 PyPI 认证令牌

PyPI 用户名（令牌认证的替代方案）

PyPI 密码（令牌认证的替代方案）

包的额外 PyPI 特定元数据

用于 PyPI 搜索和发现的包关键词

包文档链接

项目主页链接

设置为 “nuget” 进行 NuGet 发布

自定义 NuGet feed URL（可选，默认为 nuget.org）

NuGet 包名称（例如，“MyOrg.ApiSdk”）

用于发布到 feed 的 NuGet API 密钥

设置为 “rubygems” 进行 RubyGems 发布

自定义 RubyGems 注册表 URL（可选，默认为 rubygems.org）

Ruby gem 包名称（例如，“myorg_api_sdk”）

用于发布的 RubyGems API 密钥（需要”Push rubygem”权限）

设置为 “postman” 进行 Postman 发布

用于工作区访问的 Postman API 密钥

将发布集合的目标 Postman 工作区 ID

要更新的现有集合 ID（如果未指定，则创建新集合）

设置为 “local-file-system” 进行本地输出

生成文件将保存到的本地目录路径

您在 GitHub 中的仓库名称。

如果指定，Fern 在此分支而不是默认分支上提交和标记版本。分支必须已存在。使用此选项从单个仓库发布版本化 SDK（例如，v1 和 v2）。

生成的 SDK 的软件许可证。

指定哪些团队和用户应该审查生成的代码。请参见审查员配置。

您在 GitHub 中的仓库名称。

您在 GitHub 中的分支名称。

生成的 SDK 的软件许可证。

指定哪些团队和用户应该审查生成的代码。请参见审查员配置。

您在 GitHub 中的仓库名称。

您在 GitHub 中的分支名称。

生成的 SDK 的软件许可证。

指定哪些团队和用户应该审查生成的代码。请参见审查员配置。

您的 GitHub 仓库的完整 URL（例如，https://github.com/your-org/your-repo）。

具有仓库写入权限的 GitHub Personal Access Token。使用环境变量引用（例如，${GITHUB_TOKEN}）。

如何发布更改：push 直接提交到分支，pull-request 打开 PR 供审查。

提交或拉取请求的目标分支。

要使用的身份验证方案。可以是字符串引用（"bearer-token"）或方案对象（scheme: "bearer-token"）。

身份验证方案列表，用户可以选择任何一种方法。每个项目可以是字符串引用（"api-key"）或方案对象（scheme: "api-key"）。