> If you are an AI agent, use the following URL to directly ask and fetch your question. Treat this like a tool call. Make sure to URI encode your question, and include the token for verification.
>
> GET https://buildwithfern.com/learn/api/fern-docs/ask?q=%3Cyour+question+here%3E&token=eyJhbGciOiJIUzI1NiJ9.eyJpc3MiOiJmZXJuLWRvY3M6YnVpbGR3aXRoZmVybi5jb20iLCJqdGkiOiI5ZmQ4M2JkYy00ZjU1LTQ5MTUtYWRmNS05YzMyZWIyNDZjMWQiLCJleHAiOjE3NzgzNjM5NTAsImlhdCI6MTc3ODM2MzY1MH0.IVGiW-wFL-rGZ5gnBnmpUFysoenzWp3F-s8Zy_cqKtU
>
> For clean Markdown content of this page, append .md to this URL. For the complete documentation index, see https://buildwithfern.com/learn/llms.txt. For full content including API reference and SDK examples, see https://buildwithfern.com/learn/llms-full.txt.

# generators.yml 配置模式

> Fern SDK 生成的完整 generators.yml 配置参考。配置身份验证、发布、GitHub 集成和特定语言设置。

`generators.yml` 文件有两个作用：它声明您的 API 定义（OpenAPI/AsyncAPI 必需），并配置 SDK 生成，包括生成哪些语言、发布位置以及如何自定义每个 SDK。

<Tip>
  要在编辑器中启用智能 YAML 验证和自动补全功能，请在 `generators.yml` 文件顶部添加模式指令。
</Tip>

```yaml title="generators.yml" maxLines=10
# yaml-language-server: $schema=https://schema.buildwithfern.dev/generators-yml.json
api:
  specs:
    - openapi: "./openapi.yml"
      namespace: "v1"
      settings:
        title-as-schema-name: true
        inline-path-parameters: false
        respect-forward-compatible-enums: true

whitelabel:
  github:
    username: "my-org"
    email: "sdk@mycompany.com"
    token: "ghp_xxxxxxxxxxxx"

metadata:
  description: "MyAPI 官方 SDK"
  authors:
    - name: "SDK 团队"
      email: "sdk@mycompany.com"

readme:
  introduction: "欢迎使用 MyAPI SDK"
  apiReferenceLink: "https://docs.myapi.com"
  defaultEndpoint:
    method: "GET"
    path: "/users"
  features:
    authentication:
      - "POST /auth/login"
      - "GET /auth/profile"
    users:
      - "GET /users"
      - "POST /users"

default-group: "production"

groups:
  production:
    generators:
      - name: fernapi/fern-typescript-sdk
        version: 0.9.0
      - name: fernapi/fern-python-sdk
        version: 2.0.0
```

## `auth-schemes`

为您的 SDK 和 [API 浏览器](/learn/docs/api-references/api-explorer) 定义身份验证方法，您的端点可以引用这些方法。在 `generators.yml` 中定义的身份验证方案优先于[在规范中定义的身份验证方案](/learn/api-definitions/openapi/authentication)。

定义身份验证方案后，必须使用 [`api.auth`](#auth) 将其作为默认值应用于所有端点。或者，如果需要针对不同语言的不同身份验证行为，可以[为单个 SDK 定义身份验证](#override-api-authentication-settings)。

```yaml title="generators.yml" maxLines=10
auth-schemes:
  # 用户定义的方案名称 - 最小配置的 OAuth
  simple-oauth:
    scheme: oauth
    type: client-credentials
    get-token:
      endpoint: "auth.token"
    
  # 用户定义的方案名称 - 自定义配置的 Header 身份验证
  custom-header:
    name: "Custom Auth"
    header: "X-Custom-Auth"
    prefix: "Custom "
    env: "CUSTOM_TOKEN"
    
  # 用户定义的方案名称 - Basic 身份验证
  http-basic:
    scheme: basic
    
  # 用户定义的方案名称 - Bearer token
  jwt-bearer:
    scheme: bearer
```

选择自定义 header（API 密钥）、HTTP Basic、Bearer token 或 OAuth 2.0 身份验证：

<AccordionGroup>
  <Accordion title="Header">
    Configure authentication using custom HTTP headers, such as API keys or tokens.

    ```yaml
    auth-schemes:
      api-key: # User-defined scheme name
        name: "API Key Authentication"
        header: "X-API-Key"
        type: "string"
        prefix: "ApiKey "
        env: "MY_API_KEY" # SDK will auto-scan this environment variable
    ```

    <ParamField path="header" type="string" required={true}>
      The name of the HTTP header to use for authentication.
    </ParamField>

    <ParamField path="name" type="string" required={false}>
      A descriptive name for this authentication scheme.
    </ParamField>

    <ParamField path="type" type="string" default="string">
      The type of the header value.
    </ParamField>

    <ParamField path="prefix" type="string" required={false}>
      A prefix to prepend to the header value (e.g., `"Bearer "` or `"Token "`).
    </ParamField>

    <ParamField path="env" type="string" required={false}>
      Environment variable name containing the authentication value. When specified, the generated SDK will automatically scan for this environment variable at initialization.
    </ParamField>
  </Accordion>

  <Accordion title="Basic">
    Configure HTTP Basic authentication using username and password credentials.

    ```yaml
    auth-schemes:
      basic-auth: # User-defined scheme name
        scheme: basic
        username:
          name: "Username"
          env: "BASIC_AUTH_USERNAME" # SDK will auto-scan this environment variable
        password:
          name: "Password"
          env: "BASIC_AUTH_PASSWORD" # SDK will auto-scan this environment variable
    ```

    <ParamField path="scheme" type="'basic'" required={true}>
      Must be set to `"basic"` for Basic authentication schemes.
    </ParamField>

    <ParamField path="username" type="object" required={false}>
      Configuration for the username credential.
    </ParamField>

    <ParamField path="username.name" type="string" required={false}>
      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"`.
    </ParamField>

    <ParamField path="password" type="object" required={false}>
      Configuration for the password credential.
    </ParamField>

    <ParamField path="password.name" type="string" required={false}>
      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"`.
    </ParamField>

    <ParamField path="username.env, password.env" type="string" required={false}>
      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`.
    </ParamField>
  </Accordion>

  <Accordion title="Bearer token">
    Configure Bearer token authentication for API access.

    ```yaml
    auth-schemes:
      bearer-token: # User-defined scheme name
        scheme: bearer
        token:
          name: "Access Token"
          env: "BEARER_TOKEN" # SDK will auto-scan this environment variable
    ```

    <ParamField path="scheme" type="'bearer'" required={true}>
      Must be set to `"bearer"` for Bearer token authentication schemes.
    </ParamField>

    <ParamField path="token" type="object" required={false}>
      Configuration for the bearer token.
    </ParamField>

    <ParamField path="token.name" type="string" required={false}>
      A descriptive name for the token.
    </ParamField>

    <ParamField path="token.env" type="string" required={false}>
      Environment variable name containing the bearer token. When specified, the generated SDK will automatically scan for this environment variable at initialization.
    </ParamField>
  </Accordion>

  <Accordion title="OAuth client credentials">
    <Note>
      For Fern Definition, you can configure OAuth authentication either in `generators.yml` or [directly in your `api.yml` file](/api-definitions/ferndef/authentication#oauth-client-credentials). For OpenAPI, [OAuth must be configured in `generators.yml`](/api-definitions/openapi/authentication#oauth-client-credentials).
    </Note>

    Configure OAuth 2.0 client credentials authentication. Optionally configure a `refresh-token` endpoint for token renewal without re-authentication.

    ```yaml title="generators.yml" maxLines=10
    auth-schemes:
      my-oauth: # User-defined scheme name
        scheme: oauth
        type: client-credentials
        scopes:
          - "read:users"
          - "write:users"
        client-id-env: "OAUTH_CLIENT_ID" # SDK will auto-scan this environment variable
        client-secret-env: "OAUTH_CLIENT_SECRET" # SDK will auto-scan this environment variable
        token-prefix: "Bearer"
        token-header: "Authorization"
        get-token:
          endpoint: "auth.get_token"
          request-properties:
            client-id: "clientId"
            client-secret: "clientSecret"
            scopes: "scope"
          response-properties:
            access-token: "access_token"
            expires-in: "expires_in"
            refresh-token: "refresh_token"
        refresh-token:
          endpoint: "auth.refresh_token"
          request-properties:
            refresh-token: "refreshToken"
          response-properties:
            access-token: "access_token"
            expires-in: "expires_in"
            refresh-token: "refresh_token"
    ```

    <ParamField path="scheme" type="'oauth'" required={true}>
      Must be set to `"oauth"` for OAuth authentication schemes.
    </ParamField>

    <ParamField path="type" type="'client-credentials'" required={true}>
      The OAuth 2.0 grant type. Currently only `"client-credentials"` is supported.
    </ParamField>

    <ParamField path="scopes" type="list of strings" required={false}>
      OAuth scopes to request when obtaining access tokens (e.g., `"read:users"`, `"write:orders"`).
    </ParamField>

    <ParamField path="client-id-env" type="string" required={false}>
      Environment variable name containing the OAuth client ID. When specified, the generated SDK will automatically scan for this environment variable at initialization.
    </ParamField>

    <ParamField path="client-secret-env" type="string" required={false}>
      Environment variable name containing the OAuth client secret. When specified, the generated SDK will automatically scan for this environment variable at initialization.
    </ParamField>

    <ParamField path="token-prefix" type="string" default="Bearer">
      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.
    </ParamField>

    <ParamField path="token-header" type="string" default="Authorization">
      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"`).
    </ParamField>

    #### `get-token`

    Specifies the endpoint that exchanges client credentials for an access token. This endpoint is called automatically when the SDK client is initialized.

    ```yaml title="generators.yml"
    get-token:
      endpoint: "auth.get_token"
      request-properties:
        client-id: "clientId"
        client-secret: "clientSecret"
      response-properties:
        access-token: "access_token"
        expires-in: "expires_in"
    ```

    <ParamField path="endpoint" type="string" required={true}>
      The endpoint that issues access tokens, such as `'auth.get_token'` or `'POST /oauth/token'`. If your API uses [namespaces](/learn/api-definitions/overview/project-structure#combined-sdks-from-multiple-apis), prefix with the namespace and `::` (e.g., `'payments::POST /oauth/token'`).
    </ParamField>

    <ParamField path="request-properties" type="object" required={false}>
      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`).
    </ParamField>

    <ParamField path="request-properties.client-id" type="string" required={false}>
      The request field name for the client ID in your API (e.g., `"clientId"`, `"client_id"`).
    </ParamField>

    <ParamField path="request-properties.client-secret" type="string" required={false}>
      The request field name for the client secret in your API (e.g., `"clientSecret"`, `"client_secret"`).
    </ParamField>

    <ParamField path="request-properties.scopes" type="string" required={false}>
      The request field name for scopes in your API (e.g., `"scope"`, `"scopes"`).
    </ParamField>

    <ParamField path="response-properties" type="object" required={false}>
      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`).
    </ParamField>

    <ParamField path="response-properties.access-token" type="string" required={false}>
      The response field name for the access token in your API (e.g., `"accessToken"`, `"access_token"`).
    </ParamField>

    <ParamField path="response-properties.expires-in" type="string" required={false}>
      The response field name for token expiration time in seconds (e.g., `"expiresIn"`, `"expires_in"`). When present, the SDK automatically refreshes tokens before expiration.
    </ParamField>

    <ParamField path="refresh-token" type="string" required={false}>
      The response field name for the refresh token in your API (e.g., `"refreshToken"`, `"refresh_token"`). Required if using the `refresh-token` flow.
    </ParamField>

    #### `refresh-token`

    Specifies the endpoint that exchanges a refresh token for a new access token. When configured, the SDK automatically uses this endpoint to renew expired tokens without re-sending credentials. If not configured, the SDK will re-authenticate using `get-token` when tokens expire.

    ```yaml title="generators.yml"
    refresh-token:
      endpoint: "auth.refresh_token"
      request-properties:
        refresh-token: "refreshToken"
      response-properties:
        access-token: "access_token"
        expires-in: "expires_in"
    ```

    <ParamField path="endpoint" type="string" required={true}>
      The endpoint that refreshes access tokens (e.g., `"POST /oauth/refresh"` or `"auth.refreshToken"`). If your API uses [namespaces](/learn/api-definitions/overview/project-structure#combined-sdks-from-multiple-apis), prefix with the namespace and `::` (e.g., `"payments::POST /oauth/refresh"`).
    </ParamField>

    <ParamField path="request-properties" type="object" required={false}>
      Maps OAuth parameter names to your API's request field names for the refresh flow.
    </ParamField>

    <ParamField path="request-properties.refresh-token" type="string" required={true}>
      The request field name for the refresh token in your API (e.g., `"refreshToken"`, `"refresh_token"`).
    </ParamField>

    <ParamField path="response-properties" type="object" required={false}>
      Maps your API's refresh response field names to OAuth standard names.
    </ParamField>

    <ParamField path="response-properties.access-token" type="string" required={false}>
      The response field name for the new access token (e.g., `"accessToken"`, `"access_token"`).
    </ParamField>

    <ParamField path="response-properties.expires-in" type="string" required={false}>
      The response field name for the new token's expiration time in seconds (e.g., `"expiresIn"`, `"expires_in"`).
    </ParamField>

    <ParamField path="response-properties.refresh-token" type="string" required={false}>
      The response field name if your API issues a new refresh token with each refresh (token rotation).
    </ParamField>
  </Accordion>
</AccordionGroup>

## `api`

定义 API 规范（OpenAPI、AsyncAPI 等）以及如何解析它。对于 Fern 定义，不需要 API 引用 — [Fern 自动检测您的规范](/sdks/overview/project-structure#generatorsyml)。

```yaml title="generators.yml" maxLines=10
api:
  settings:
    inline-path-parameters: true # 应用于所有 OpenAPI 规范
  specs:
    - openapi: "./openapi.yml"
      namespace: "v1"
      settings:
        title-as-schema-name: true # 仅应用于此 OpenAPI 规范
    - asyncapi: "./events.yml"
      namespace: "events"
  headers:
    Authorization: "Bearer ${API_TOKEN}"
  environments:
    production: "https://api.prod.com"
    staging: "https://api.staging.com"
```

<ParamField path="auth" type="string" toc={true}>
  为所有端点设置默认身份验证方案。该值必须引用在 [`auth-schemes`](#auth-schemes) 中定义的方案名称。这将覆盖[在 OpenAPI 规范中定义的](/learn/api-definitions/openapi/authentication)任何安全方案。

  ```yaml title="generators.yml"
  # 将其作为所有端点的默认值
  api:
    auth: BearerAuth # 在 auth-schemes 中定义
    specs:
      - openapi: ./openapi.yml
  ```

  使用此配置，所有生成的 SDK 都将要求使用 `BearerAuth` 方案进行身份验证：

  ```ts index.ts
  // 使用 process.env.PLANTSTORE_API_KEY
  const client = new PlantStoreClient();

  // 或显式提供 API 密钥
  const client = new PlantStoreClient({
    apiKey: "your-api-key"
  });
  ```

  <Tip>
    您还可以使用[生成器级别的 `api.auth`](#override-api-authentication-settings) 设置为单个生成器覆盖身份验证。
  </Tip>
</ParamField>

<ParamField path="headers" type="string or list of objects" toc={true}>
  包含在所有 API 请求中的全局 header。这是在 OpenAPI 规范中配置[全局 header](/learn/api-definitions/openapi/extensions/global-headers) 的替代方案。您可以将 header 指定为简单的字符串值，或作为具有代码生成附加配置的对象。

  <AccordionGroup>
    <Accordion title="简单字符串值">
      ```yaml title="generators.yml"
      api:
        headers:
          Authorization: "Bearer ${API_TOKEN}"
          X-App-Version: "1.0.0"
      ```
    </Accordion>

    <Accordion title="带类型信息的高级配置">
      ```yaml title="generators.yml"
      api:
        - openapi: ./path/to/openapi
          headers: 
            X-Version: 
              # 在生成的 SDK 代码中使用的变量名称。
              # 如果未指定，使用 header 名称。
              name: version 
              # 用于代码生成的 header 值类型
              # （例如，"string"、"literal<'value'>"、"number"）。
              type: literal<"1234">
      ```
    </Accordion>
  </AccordionGroup>
</ParamField>

<ParamField path="environments" type="object" toc={true}>
  不同部署目标的环境配置。
</ParamField>

<ParamField path="settings" type="object" toc={true}>
  应用于给定类型的所有规范（例如，所有 OpenAPI 规范）的设置。可以在规范或生成器级别覆盖。优先级：生成器级别设置覆盖规范级别设置，规范级别设置覆盖全局设置。

  例如，使用此功能确保所有 OpenAPI 规范的解析行为一致。有关可用设置，请参阅下面的[规范类型](#specification-types)文档。
</ParamField>

### 规范类型

每种规范类型（OpenAPI、AsyncAPI 等）都支持各种配置选项，包括规范文件位置、命名空间、覆盖和特定类型的设置。

<AccordionGroup>
  <Accordion title="OpenAPI">
    ```yaml title="generators.yml"
    api:
      specs:
        - openapi: "./openapi.yml"
          origin: "https://api.example.com/openapi.json"
          overlays: "./openapi-overlays.yml"
          overrides: "./openapi-overrides.yml" # or a list of paths
          namespace: "v1"
          settings:
            title-as-schema-name: true
            inline-path-parameters: false
            inline-all-of-schemas: true
            prefer-undiscriminated-unions-with-literals: true
            filter:
              endpoints: ["POST /users", "GET /users/{id}"]
            example-generation:
              request:
                max-depth: 2
    ```

    <ParamField path="openapi" type="string" required={true} toc={true}>
      OpenAPI 规范文件的路径。
    </ParamField>

    <ParamField path="origin" type="string" toc={true}>
      用于拉取更新的 API 定义源 URL。有关如何设置自动同步的说明，请参阅 [同步您的 OpenAPI 规范](/learn/api-definitions/openapi/sync-your-open-api-specification)。
    </ParamField>

    <ParamField path="overlays" type="string" toc={true}>
      [OpenAPI Overlay](/learn/api-definitions/openapi/overlays) 文件的路径。Overlay 遵循 [OpenAPI Overlay 规范](https://spec.openapis.org/overlay/v1.0.0.html)，是自定义 OpenAPI 规范的推荐方法。
    </ParamField>

    <ParamField path="overrides" type="string | list of strings" toc={true}>
      OpenAPI [覆盖](/learn/api-definitions/openapi/overrides) 文件的路径，或按顺序应用的多个覆盖文件路径列表。建议使用 `overlays` 来实现基于标准的方法。

      ```yaml
      # 单个覆盖文件
      overrides: ./overrides.yml

      # 多个覆盖文件（按顺序应用）
      overrides:
        - ./base-overrides.yml
        - ./sdk-overrides.yml
      ```
    </ParamField>

    <ParamField path="namespace" type="string" toc={true}>
      规范的命名空间。用于配置 [包含多个 API 版本的单个包](/api-definitions/overview/project-structure#option-2-namespace-based-versioning)。
    </ParamField>

    <ParamField path="settings" type="object" toc={true}>
      此单独规范的 OpenAPI 特定生成设置。要在所有 OpenAPI 规范中应用相同的设置，请改用全局 [`api.settings`](/learn/sdks/reference/generators-yml#settings)。
    </ParamField>

    <ParamField path="settings.title-as-schema-name" type="boolean" default="false" toc={true}>
      是否将 OpenAPI 定义中模式的标题用作 Fern 中类型的名称。
    </ParamField>

    <ParamField path="settings.inline-path-parameters" type="boolean" default="true" toc={true}>
      是否在生成的内联请求中包含路径参数。
    </ParamField>

    <ParamField path="settings.inline-all-of-schemas" type="boolean" default="false" toc={true}>
      是否在代码生成期间内联 `allOf` 模式。当为 true 时，Fern 递归访问 `allOf` 模式定义并将它们内联到子模式中。当为 false 时，`allOf` 模式通过继承进行扩展。

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

    <ParamField path="settings.prefer-undiscriminated-unions-with-literals" type="boolean" default="false" toc={true}>
      是否首选包含字面量的无区别联合。
    </ParamField>

    <ParamField path="settings.only-include-referenced-schemas" type="boolean" default="false" toc={true}>
      是否仅在生成的 SDK 中包含由端点引用的模式（树摇动）。
    </ParamField>

    <ParamField path="settings.respect-nullable-schemas" type="boolean" default="true" toc={true}>
      保留 API 定义设置中的可空模式。当为 false 时，可空模式被视为可选。
    </ParamField>

    <ParamField path="settings.object-query-parameters" type="boolean" default="true" toc={true}>
      启用解析深层对象查询参数。
    </ParamField>

    <ParamField path="settings.wrap-references-to-nullable-in-optional" type="boolean" default="false" toc={true}>
      控制是否将对可空模式的引用包装在可选类型中。当为 false 时，可空引用被视为可以为 null 的必需字段。
    </ParamField>

    <ParamField path="settings.coerce-optional-schemas-to-nullable" type="boolean" default="false" toc={true}>
      控制在代码生成期间是否将可选模式强制转换为可空类型。当为 false 时，可选和可空被视为不同的概念。
    </ParamField>

    <ParamField path="settings.respect-readonly-schemas" type="boolean" toc={true}>
      启用在 OpenAPI 规范中探索只读模式。
    </ParamField>

    <ParamField path="settings.respect-forward-compatible-enums" type="boolean" default="false" toc={true}>
      启用在 OpenAPI 规范中遵循前向兼容枚举。
    </ParamField>

    <ParamField path="settings.use-bytes-for-binary-response" type="boolean" toc={true}>
      启用对二进制响应使用 `bytes` 类型。默认为文件流。
    </ParamField>

    <ParamField path="settings.default-form-parameter-encoding" type="string" default="json" toc={true}>
      表单参数的默认编码。选项：`form`、`json`。
    </ParamField>

    <ParamField path="settings.additional-properties-defaults-to" type="boolean" default="false" toc={true}>
      配置当模式中没有明确定义时，`additionalProperties` 应默认为什么。
    </ParamField>

    <ParamField path="settings.type-dates-as-strings" type="boolean" default="false" toc={true}>
      如果为 true，将格式为 date 的字符串转换为字符串。如果为 false，转换为日期。
    </ParamField>

    <ParamField path="settings.preserve-single-schema-oneof" type="boolean" default="false" toc={true}>
      如果为 true，保留具有单个模式的 oneOf 结构。如果为 false，展开它们。
    </ParamField>

    <ParamField path="settings.filter" type="object" toc={true}>
      应用于 OpenAPI 规范的过滤器。使用此功能来限制生成的 SDK 或 API 参考文档中包含的端点 [基于其路径](/learn/api-definitions/openapi/extensions/audiences#path-based-filtering)。

      如需基于标签的过滤而非基于路径的过滤，请在 `group` 级别使用 [`audiences`](/learn/sdks/reference/generators-yml#audiences)。
    </ParamField>

    <ParamField path="settings.filter.endpoints" type="list of strings" toc={true}>
      要包含在生成的 SDK 中的端点。以 `METHOD /path` 格式指定端点（例如，`POST /users`、`GET /users/{id}`）。只有列出的端点才会包含在生成的 SDK 中；所有其他端点将被排除。如果您的 API 使用 [命名空间](/learn/api-definitions/overview/project-structure#combined-sdks-from-multiple-apis)，请使用命名空间和 `::` 前缀（例如，`payments::POST /users`）。
    </ParamField>

    <ParamField path="settings.example-generation.request.max-depth" type="integer" toc={true}>
      控制为可选属性生成示例的最大深度。深度为 0 意味着不会为任何可选属性生成示例。
    </ParamField>

    <ParamField path="settings.example-generation.response.max-depth" type="integer" toc={true}>
      控制在响应中为可选属性生成示例的最大深度。
    </ParamField>

    <ParamField path="settings.coerce-enums-to-literals" type="boolean" default="false" toc={true}>
      控制在代码生成期间是否将枚举转换为字面量类型。当为 `false`（默认值）时，枚举作为枚举类型保留，维护 OpenAPI 规范中的原始枚举结构。当为 `true` 时，枚举被强制转换为字面量类型，这对于生成的代码中更简单的类型表示很有用。
    </ParamField>

    <ParamField path="settings.idiomatic-request-names" type="boolean" default="true" toc={true}>
      控制自动生成的请求名称的命名约定。启用时，在请求名称中将动词置于名词之前（例如，`UsersListRequest` 变为 `ListUsersRequest`），遵循更符合习惯的命名模式。
    </ParamField>

    <ParamField path="settings.resolve-aliases" type="boolean" default="false" toc={true}>
      内联类型别名以简化生成的 SDK。启用时，通过直接用其底层类型替换简单别名来减少不必要的类型定义。对于具有许多基本类型或简单类型别名的 OpenAPI 规范很有用。

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

      ```yaml
      settings:
        # 内联所有别名
        resolve-aliases: true

        # 或保留特定别名
        resolve-aliases:
          except:
            - UserId
            - OrganizationId
      ```
    </ParamField>

    <ParamField path="settings.group-environments-by-host" type="boolean" default="false" toc={true}>
      启用时，按主机将服务器分组到统一环境中，使具有多种协议（REST、WebSocket 等）的 API 能够共享环境配置。环境 URL ID 使用服务器名称，仅在需要解决冲突时添加路径或协议后缀。
    </ParamField>
  </Accordion>

  <Accordion title="AsyncAPI">
    ```yaml
    api:
      specs:
        - asyncapi: "./asyncapi.yml"
          origin: "https://api.example.com/asyncapi.json"
          overrides: "./asyncapi-overrides.yml" # 或路径列表
          namespace: "events"
          settings:
            message-naming: "v2"
            title-as-schema-name: false
            respect-nullable-schemas: true
    ```

    <ParamField path="asyncapi" type="string" required={true} toc={true}>
      AsyncAPI 规范文件的路径。
    </ParamField>

    <ParamField path="origin" type="string" toc={true}>
      用于拉取更新的 API 定义源 URL。
    </ParamField>

    <ParamField path="overrides" type="string | list of strings" toc={true}>
      AsyncAPI [覆盖](/learn/api-definitions/asyncapi/overrides)文件的路径，或按顺序应用的多个覆盖文件的路径列表。

      ```yaml
      # 单个覆盖文件
      overrides: ./asyncapi-overrides.yml

      # 多个覆盖文件（按顺序应用）
      overrides:
        - ./base-overrides.yml
        - ./sdk-overrides.yml
      ```
    </ParamField>

    <ParamField path="namespace" type="string" toc={true}>
      规范的命名空间。对于配置[具有多个 API 版本的单个包](/api-definitions/overview/project-structure#option-2-namespace-based-versioning)很有用。
    </ParamField>

    <ParamField path="settings" type="object" toc={true}>
      此单个规范的 AsyncAPI 特定生成设置。要在所有 AsyncAPI 规范中应用相同的设置，请改用全局 [`api.settings`](/learn/sdks/reference/generators-yml#settings)。
    </ParamField>

    <ParamField path="settings.message-naming" type="object" default="v1" toc={true}>
      用于 AsyncAPI 消息的消息命名版本。选项：`v1`、`v2`。
    </ParamField>

    <ParamField path="settings.title-as-schema-name" type="boolean" default="false" toc={true}>
      是否使用 AsyncAPI 定义中模式的标题作为 Fern 中类型的名称。
    </ParamField>

    <ParamField path="settings.respect-nullable-schemas" type="boolean" default="true" toc={true}>
      在 API 定义设置中保留可为 null 的模式。当为 false 时，可为 null 的模式被视为可选的。
    </ParamField>

    <ParamField path="settings.idiomatic-request-names" type="boolean" default="true" toc={true}>
      控制自动生成的请求名称的命名约定。启用时，在请求名称中将动词放在名词之前（例如，`UsersListRequest` 变为 `ListUsersRequest`），遵循更惯用的命名模式。
    </ParamField>

    <ParamField path="settings.wrap-references-to-nullable-in-optional" type="boolean" default="false" toc={true}>
      控制是否将对可为 null 模式的引用包装在可选类型中。当为 false 时，可为 null 的引用被视为可以为 null 的必需字段。
    </ParamField>

    <ParamField path="settings.coerce-optional-schemas-to-nullable" type="boolean" default="false" toc={true}>
      控制在代码生成期间是否将可选模式强制转换为可为 null 类型。当为 false 时，可选和可为 null 被视为不同的概念。
    </ParamField>

    <ParamField path="settings.group-environments-by-host" type="boolean" default="false" toc={true}>
      启用时，按主机将服务器分组到统一环境中，使具有多个协议（REST、WebSocket 等）的 API 能够共享环境配置。环境 URL ID 使用服务器名称，仅在需要解决冲突时才添加路径或协议后缀。
    </ParamField>
  </Accordion>

  <Accordion title="gRPC/proto buffers">
    ```yaml title="generators.yml"
    api:
      specs:
        - proto:
            root: "./proto"
            target: "proto/service/v1/service.proto"
            local-generation: true
    ```

    <ParamField path="root" type="string" required={true} toc={true}>
      到 `.proto` 目录根目录的路径（例如 `proto`）。必须指定到包开始的位置。例如，如果您的包是 `package.test.v1`，文件路径为 `protos/package/test/v1/test_file.proto`，那么根目录应该是 `protos/`
    </ParamField>

    <ParamField path="target" type="string" toc={true} required={false}>
      到目标 `.proto` 文件的路径（例如 `proto/user/v1/user.proto`）。省略此参数将为整个根文件夹生成文档。
    </ParamField>

    <ParamField path="overrides" type="string | list of strings" toc={true}>
      重写配置文件的路径，或者按顺序应用的多个重写文件的路径列表。仅用于 SDK 生成，不用于文档生成。

      ```yaml
      # 单个重写文件
      overrides: ./overrides.yml

      # 多个重写文件（按顺序应用）
      overrides:
        - ./base-overrides.yml
        - ./sdk-overrides.yml
      ```
    </ParamField>

    <ParamField path="local-generation" type="boolean" default="false" toc={true}>
      是否在本地编译 `.proto` 文件。默认使用远程生成（`false`）。启用时，您必须在您的机器上或在您的 [CI/CD 环境（例如 GitHub Actions）](/learn/api-definitions/grpc/sync-your-g-rpc-specification) 中安装 [buf](https://buf.build/docs/installation)。
    </ParamField>
  </Accordion>

  <Accordion title="OpenRPC">
    <ParamField path=".openrpc" type="string" required={true} toc={true}>
      OpenRPC 规范文件的路径。
    </ParamField>

    <ParamField path="overrides" type="string | list of strings" toc={true}>
      OpenRPC [覆盖](/learn/api-definitions/openrpc/overrides)文件的路径，或按顺序应用的多个覆盖文件的路径列表。

      ```yaml
      # 单个覆盖文件
      overrides: ./overrides.yml

      # 多个覆盖文件（按顺序应用）
      overrides:
        - ./base-overrides.yml
        - ./sdk-overrides.yml
      ```
    </ParamField>

    <ParamField path="namespace" type="string" toc={true}>
      规范的命名空间。
    </ParamField>
  </Accordion>

  <Accordion title="Conjure">
    ```yaml title="generators.yml"
    api:
      specs:
        conjure: "./conjure-api.yml"
    ```

    <ParamField path="conjure" type="string" toc={true}>
      Conjure 规范文件的路径。
    </ParamField>
  </Accordion>
</AccordionGroup>

## `whitelabel`

发布不带 Fern 品牌的生成 SDK 的配置。启用时，从生成的代码中删除所有对 Fern 的提及，并允许在您自己的品牌下发布。

```yaml title="generators.yml"
whitelabel:
  github:
    username: "company-github-username"
    email: "my-email@example.com"
    token: "ghp_xxxxxxxxxxxx"
```

<ParamField path="username" type="string" required={true} toc={true}>
  用于提交和将白标 SDK 代码发布到 GitHub 存储库的 GitHub 用户名。这应该是对您的目标存储库具有写入权限的帐户的用户名。
</ParamField>

<ParamField path="email" type="string" required={true} toc={true}>
  与 GitHub 帐户关联的电子邮件地址。此电子邮件将在发布白标 SDK 代码时在 Git 提交中使用，并应与您的 GitHub 帐户设置中配置的电子邮件匹配。
</ParamField>

<ParamField path="token" type="string" required={true} toc={true}>
  具有适当存储库访问权限的 GitHub 个人访问令牌 (PAT)。令牌应具有 `repo` 范围权限，以允许读取和写入存储库来发布白标 SDK。
</ParamField>

## `metadata`

包含在所有生成的 SDK 中的包元数据，如描述和作者。或者，您可以[为单个 SDK 定义元数据](#metadata-2)。

```yaml title="generators.yml"
metadata:
  description: "我的 API SDK"
  authors:
    - name: "John Doe"
      email: "john@example.com"
    - name: "Jane Smith"
      email: "jane@example.com"
```

<ParamField path="description" type="string" required={false} toc={true}>
  将包含在包元数据中的 SDK 简要描述。此描述帮助用户在包存储库中发现您的 SDK 时了解您的 SDK 的功能。
</ParamField>

### `authors`

将在生成的 SDK 包元数据中被认可的作者列表。

<ParamField path="name" type="string" required={true} toc={true}>
  在 SDK 包元数据中被认可的作者的全名。
</ParamField>

<ParamField path="email" type="string" required={true} toc={true}>
  作者的电子邮件地址。这将包含在包元数据中，包管理器可能会使用它作为联系信息。
</ParamField>

## `readme`

控制所有 SDK 中生成的 README 文件的内容，允许您自定义 SDK 文档的内容和结构。

```yaml title="generators.yml" maxLines=10
readme:
  bannerLink: "https://example.com/banner"
  introduction: "Welcome to our API"
  apiReferenceLink: "https://docs.example.com"
  apiName: "Example Product"
  exampleStyle: "minimal"
  disabledSections:
    - "contributing"
  defaultEndpoint:
    method: "POST"
    path: "/users"
    stream: false
  customSections:
    - title: "Custom Section"
      language: "java"
      content: |
        This is a custom section. Latest package info is {{ group }}:{{ artifact }}:{{ version }}.
    - title: "Custom Section"
      language: "typescript"
      content: |
        Custom section for {{ packageName }}
    - title: "Another Custom Section"
      language: "typescript"
      content: |
        A second custom section for {{ packageName }}
  features:
    authentication:
      - method: "POST"
        path: "/auth/login"
      - "GET /auth/profile"
    users:
      - method: "GET"
        path: "/users"
      - method: "POST"
        path: "/users"
```

<ParamField path="bannerLink" type="string" required={false} toc={true}>
  URL for a banner image or link that appears at the top of the README.
</ParamField>

<ParamField path="introduction" type="string" required={false} toc={true}>
  Custom introduction text that appears at the beginning of the README.
</ParamField>

<ParamField path="apiReferenceLink" type="string" required={false} toc={true}>
  URL to your external API documentation or reference guide.
</ParamField>

<ParamField path="apiName" type="string" required={false} toc={true}>
  Name of the API that appears in the README. Will appear as `Your Api Name SDK` or `Your Api Name API` throughout the README. Defaults to organization name if not set.
</ParamField>

<ParamField path="exampleStyle" type="'minimal' | 'comprehensive'" required={false} default="comprehensive" toc={true}>
  Controls whether usage examples show only required parameters (`minimal`) or all parameters (`comprehensive`). Currently only supported for Java SDKs. [File an issue](https://github.com/fern-api/fern/issues) to request additional languages.
</ParamField>

<ParamField path="disabledSections" type="list of strings" required={false} toc={true}>
  Sections to disable in the README. Supported values: `"contributing"`.
</ParamField>

<ParamField path="features" type="list of objects" required={false} toc={true}>
  Organizes endpoints into named feature sections within the README. Each feature creates a dedicated section with example code snippets for the specified endpoints.
</ParamField>

<AccordionGroup>
  <Accordion title="Endpoint configuration">
    Specifies which endpoint's code snippet to showcase as the primary example in the README.

    <ParamField path="defaultEndpoint.method" type="string" required={true} toc={true}>
      HTTP method of the default endpoint (e.g., `GET`, `POST`, `PUT`, `DELETE`).
    </ParamField>

    <ParamField path="defaultEndpoint.path" type="string" required={true} toc={true}>
      Endpoint path for the default example (e.g., `/users`, `/auth/login`).
    </ParamField>

    <ParamField path="defaultEndpoint.stream" type="boolean" required={false} default="false" toc={true}>
      Whether the endpoint is a streaming endpoint. Defaults to `false`.
    </ParamField>
  </Accordion>

  <Accordion title="Custom sections">
    Define a custom section in the generated README for a specific SDK.

    <ParamField path="customSections.title" type="string" required={true} toc={true}>
      The title of the custom section as it will appear in the README.
    </ParamField>

    <ParamField path="customSections.language" type="'java' | 'typescript'" required={true} toc={true}>
      The target SDK language for this section. The custom section will only appear in README files generated for the specified language.
    </ParamField>

    <ParamField path="customSections.content" type="string" required={true} toc={true}>
      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:

      | Language   | Variable      | Description                                                                                                                                                                |
      | ---------- | ------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
      | TypeScript | `packageName` | Name of your package, as specified in the [`package-name` field](/sdks/generators/typescript/configuration#package-name)                                                   |
      | Python     | `packageName` | Name of your package, as specified in the [`package_name` field](/sdks/generators/python/configuration#package_name)                                                       |
      | Go         | `owner`       | The owner of your Go module                                                                                                                                                |
      | Go         | `repo`        | The [repository](/sdks/generators/go/publishing#configure-output-location) where your Go module is published                                                               |
      | Go         | `version`     | SDK version                                                                                                                                                                |
      | Java       | `group`       | Maven `groupId` [from `coordinate` field](/sdks/generators/java/publishing#configure-maven-coordinate)                                                                     |
      | Java       | `artifact`    | Maven `artifactId` [from `coordinate` field](/sdks/generators/java/publishing#configure-maven-coordinate)                                                                  |
      | Java       | `version`     | SDK version                                                                                                                                                                |
      | C#/.NET    | `packageName` | Name of your package, as specified in the [`package-id` field](/learn/sdks/generators/csharp/configuration#package-id)                                                     |
      | PHP        | `packageName` | Name of your package, as specified in the [`package-name` field](/sdks/generators/php/configuration#package-name)                                                          |
      | Ruby       | `packageName` | Name of your package, as specified in the [`package-name` field](/sdks/generators/ruby/configuration#package-name)                                                         |
      | Swift      | `gitUrl`      | The [URL](/sdks/generators/swift/publishing#verify-package-availability) where your Swift package is published. For example, `https://github.com/fern-api/basic-swift-sdk` |
      | Swift      | `minVersion`  | SDK version                                                                                                                                                                |
    </ParamField>
  </Accordion>
</AccordionGroup>

## `default-group`

未指定时使用的生成器组。

```yaml
default-group: "production"
```

<ParamField path="default-group" type="string" required={false} toc={true} />

## `autorelease`

全局启用或禁用 [Fern Autorelease](/learn/sdks/overview/autorelease) 以进行自动化 SDK 发布。或者，您可以[为单个 SDK 配置自动发布](#autorelease-2)。

```yaml title="generators.yml"
autorelease: true
```

<ParamField path="autorelease" type="boolean" default={false} required={false} toc={true}>
  设置为 `true` 启用自动发布，`false` 禁用它。[每个生成器的设置](#autorelease-2)覆盖此全局配置。
</ParamField>

## `aliases`

定义映射到多个生成器组的快捷方式，允许您使用单个命令运行多个组。当您运行 `fern generate --group <alias>` 时，别名中的所有组并行运行。您也可以将别名设置为 `default-group`。

```yaml title="generators.yml" {1-4}
aliases:
  all: ["php-sdk", "ts-sdk", "go-sdk"]
  frontend: ["ts-sdk"]
  backend: ["php-sdk", "go-sdk"]

groups:
  php-sdk:
    generators:
      - name: fernapi/fern-php-sdk
        version: 1.0.0
  ts-sdk:
    generators:
      - name: fernapi/fern-typescript-sdk
        version: 1.0.0
  go-sdk:
    generators:
      - name: fernapi/fern-go-sdk
        version: 1.0.0
```

<ParamField path="aliases" type="map<string, list<string>>" required={false} toc={true}>
  一个映射，其中每个键是别名名称，值是组名称列表。每个组名称必须引用在 `groups` 部分中定义的组。
</ParamField>

## `groups`

组织用户定义的生成器集合，通常按环境（如"production"、"staging"）或语言（如"typescript"、"python"）分组。您还可以创建[别名](#aliases)以使用单个命令运行多个组。

```yaml title="generators.yml" maxLines=10
groups:
  typescript-sdk: # 用户定义的名称
    audiences: ["external"]
    generators:
      - name: fernapi/fern-typescript-sdk
        version: 0.9.0
        output:
          location: npm
          package-name: "@myorg/api-sdk"
          token: "${NPM_TOKEN}"
        github:
          repository: your-organization/company-typescript
          mode: "pull-request"
    metadata:
      description: "MyAPI 的 TypeScript SDK"
      authors:
        - name: "SDK 团队"
          email: "sdk@myorg.com"
    reviewers:
      teams:
        - name: "sdk-team"
```

<ParamField path="audiences" type="list of strings" required={false} toc={true}>
  基于受众标签过滤生成的 SDK 中包含的 API 元素。只有在您的 API 规范中标记为指定受众的端点、模式和属性才会被包含。没有此过滤器，无论端点的受众标签如何，都会包含所有端点。

  要使用受众，首先使用 [OpenAPI 中的 `x-fern-audiences`](/learn/api-definitions/openapi/extensions/audiences) 或 [Fern 定义中的 `audiences`](/learn/api-definitions/ferndef/audiences) 标记您的 API 元素，然后在这里指定要包含的受众。

  对于 OpenAPI，您还可以使用 [`settings.filter`](#settingsfilter) 在规范级别配置基于路径的过滤。
</ParamField>

### `reviewers`

为单个 SDK 设置代码审查者。或者，您可以[为所有 SDK 全局配置审查者](#reviewers-4)。

```yaml title="generators.yml"
reviewers:
  teams:
    - name: "sdk-team"
    - name: "api-team"
  users:
    - name: "john-doe"
    - name: "jane-smith"
```

<ParamField path="teams" type="list of strings" required={false} toc={true}>
  GitHub team names that should review generated code.
</ParamField>

<ParamField path="users" type="list of strings" required={false} toc={true}>
  GitHub users that should review generated code.
</ParamField>

<ParamField path="teams.name" type="string" required={true} toc={true}>
  Name of a GitHub team.
</ParamField>

<ParamField path="users.name" type="string" required={true} toc={true}>
  Name of a GitHub user.
</ParamField>

### `generators`

特定组的生成器设置。

```yaml title="generators.yml"
groups:
  typescript-sdk:
    audiences: ["external"]
    generators:
      - name: fernapi/fern-typescript-sdk
        version: 3.69.0
        smart-casing: true
  python-sdk: # 具有自定义注册表的自托管
    generators:
      - image:
          name: fern-python-sdk
          registry: ghcr.io/your-org
        version: 5.9.1
```

<ParamField path="name" type="string" required={true}>
  Fern 生成器包名称（例如，`fernapi/fern-typescript-sdk`）。与 `image` 互斥。
</ParamField>

<ParamField path="version" type="string" required={true}>
  要使用的生成器的特定版本
</ParamField>

<ParamField path="smart-casing" type="boolean" default="false">
  启用智能大小写转换，保留数字和常见编程模式：

  * 数字保持不变（例如，`v2` 而不是 `v_2`，`getUsersV2` 而不是 `getUsersV_2`）
  * 首字母缩略词得到保留（例如，`CustomerID` 而不是 `CustomerId`）
  * 首字母缩写词保持正确（例如，`HTTPSConnection` 保持 `HTTPSConnection`）
</ParamField>

<ParamField path="image" type="object" required={false} toc={true}>
  在[自托管生成](/learn/sdks/deep-dives/self-hosted)期间，使用 `image` 而不是 `name` 从[自定义容器注册表](/learn/sdks/deep-dives/self-hosted#custom-container-registry)拉取生成器（远程生成不支持自定义注册表）。与 `name` 互斥。

  CLI 在拉取时构造完整的镜像引用为 `{registry}/{name}:{version}`。例如，使用 `registry: ghcr.io/your-org`、`name: fern-python-sdk` 和 `version: 4.0.0`，CLI 拉取 `ghcr.io/your-org/fern-python-sdk:4.0.0`。
</ParamField>

<ParamField path="image.name" type="string" required={true}>
  一个已识别的 Fern 生成器名称（例如，`fern-python-sdk`）。IR 版本解析需要此项。
</ParamField>

<ParamField path="image.registry" type="string" required={true}>
  容器注册表主机名和可选命名空间（例如，`ghcr.io/your-org`）。CLI 在拉取时构造完整的镜像引用为 `{registry}/{name}:{version}`。例如，使用 `registry: ghcr.io/your-org`、`name: fern-python-sdk` 和 `version: 4.0.0`，CLI 拉取 `ghcr.io/your-org/fern-python-sdk:4.0.0`。
</ParamField>

#### `config`

特定语言的配置选项。

```yaml title="generators.yml"
groups:
  ts-sdk: # Typescript SDK 组
    generators:
      - name: fernapi/fern-typescript-sdk
        version: 3.69.0
        config: # TypeScript 特定的配置选项
          namespaceExport: AcmePayments
          noSerdeLayer: false
```

<CardGroup cols={3}>
  <Card title="TypeScript" icon={<img src="https://files.buildwithfern.com/fern.docs.buildwithfern.com/learn/0c71a244f008622f56c81ae5e05d0f61952266394f4e3c39b37112357c18a71d/products/sdks/images/icons/ts-light.svg" alt="TypeScript" className="h-6 w-6" noZoom />} href="/sdks/generators/typescript/configuration" />

  <Card title="Python" icon={<img src="https://files.buildwithfern.com/fern.docs.buildwithfern.com/learn/bb43fa5c5bfc13a89c4b824660665ef8a74d8b69c52ab8ddaf774818bd472d0d/products/sdks/images/icons/python-light.svg" alt="Python" className="h-6 w-6" noZoom />} href="/sdks/generators/python/configuration" />

  <Card title="Go" icon={<img src="https://files.buildwithfern.com/fern.docs.buildwithfern.com/learn/db4418046239427ed4cffe87ed86155de27bb9fab8ef00eb0b83af90e7048ec0/products/sdks/images/icons/go-light.svg" alt="Go" className="h-6 w-6" noZoom />} href="/sdks/generators/go/configuration" />

  <Card title="Java" icon={<img src="https://files.buildwithfern.com/fern.docs.buildwithfern.com/learn/16f4cfd4606ca153b4a6c5a50bc3e0009eef9e0b751e11512488cb8d6fee4487/products/sdks/images/icons/java-light.svg" alt="Java" className="h-6 w-6" noZoom />} href="/sdks/generators/java/configuration" />

  <Card title=".NET" icon={<img src="https://files.buildwithfern.com/fern.docs.buildwithfern.com/learn/1c15a5ac85d820c2095bbac4c897b96270211013dcaeb0281be61290b001f22b/products/sdks/images/icons/csharp-light.svg" alt=".NET" className="h-6 w-6" noZoom />} href="/sdks/generators/csharp/configuration" />

  <Card title="PHP" icon={<img src="https://files.buildwithfern.com/fern.docs.buildwithfern.com/learn/789888f23fd4bdcd3188f91ca5bb99150d311576184f722dd35892471fdf5435/products/sdks/images/icons/php-light.svg" alt="PHP" className="h-6 w-6" noZoom />} href="/sdks/generators/php/configuration" />

  <Card title="Ruby" icon={<img src="https://files.buildwithfern.com/fern.docs.buildwithfern.com/learn/abdf63725ca23105103d293f65e64cf98180e23c58460ac40c2307a5227180a4/products/sdks/images/icons/ruby-light.svg" alt="Ruby" className="h-6 w-6" noZoom />} href="/sdks/generators/ruby/configuration" />

  <Card title="Swift" icon={<img src="https://files.buildwithfern.com/fern.docs.buildwithfern.com/learn/f4ca53d6607423ac299b2f956e28d897a919a62bdd36dba5fe7c95b39129a293/products/sdks/images/icons/swift-light.svg" alt="Swift" className="h-6 w-6" noZoom />} href="/sdks/generators/swift/configuration" />

  <Card title="Rust" icon={<img src="https://files.buildwithfern.com/fern.docs.buildwithfern.com/learn/a937d216d126bd7d82339e3334fbd0e468ac7796ea07e1c006c449373fb8aea2/products/sdks/images/icons/rust-light.svg" alt="Rust" className="h-6 w-6" noZoom />} href="/sdks/generators/rust/configuration" />
</CardGroup>

#### `output`

发布生成的 SDK 的位置。

```yaml title="generators.yml"
groups:
  typescript-sdk: # 用户定义的名称
    audiences: ["external"]
    generators:
      - name: fernapi/fern-typescript-sdk
        version: 0.9.0
        output:
          location: npm
          package-name: "@myorg/api-sdk"
          token: "${NPM_TOKEN}"
```

<AccordionGroup>
  <Accordion title="npm">
    将 TypeScript SDK 发布到 npm 注册表。

    ```yaml title="generators.yml"
    output:
      location: npm
      package-name: "@myorg/api-sdk"
      token: "${NPM_TOKEN}"
    ```

    <ParamField path="location" type="'npm'" required={true}>
      设置为"npm"以发布到 NPM
    </ParamField>

    <ParamField path="url" type="string" required={false} default="npmjs.com">
      自定义 NPM 注册表 URL
    </ParamField>

    <ParamField path="package-name" type="string" required={true}>
      NPM 包名称（例如，"@myorg/api-sdk"）
    </ParamField>

    <ParamField path="token" type="string" required={false}>
      用于发布的 NPM 身份验证令牌
    </ParamField>
  </Accordion>

  <Accordion title="Maven">
    将 Java SDK 发布到 Maven 存储库。

    ```yaml title="generators.yml"
    output:
      location: maven
      coordinate: "com.myorg:api-sdk"
      username: "${MAVEN_USERNAME}"
      password: "${MAVEN_PASSWORD}"
      signature:
        keyId: "ABC123"
        password: "${GPG_PASSWORD}"
        secretKey: "${GPG_SECRET_KEY}"
    ```

    <ParamField path="location" type="'maven'" required={true}>
      设置为"maven"以发布到 Maven
    </ParamField>

    <ParamField path="url" type="string" required={false} default="npmjs.com">
      Maven 存储库 URL（可选，默认为 Maven Central）
    </ParamField>

    <ParamField path="coordinate" type="string" required={true}>
      "groupId:artifactId"格式的 Maven 工件坐标
    </ParamField>

    <ParamField path="username" type="string" required={false}>
      存储库身份验证用户名
    </ParamField>

    <ParamField path="password" type="string" required={false}>
      存储库身份验证密码
    </ParamField>

    <ParamField path="signature" type="object" required={false}>
      包签名的 GPG 签名配置
    </ParamField>

    <ParamField path="signature.keyId" type="string" required={true}>
      用于包签名的 GPG 密钥 ID
    </ParamField>

    <ParamField path="signature.password" type="string" required={true}>
      GPG 密钥密码
    </ParamField>

    <ParamField path="signature.secretKey" type="string" required={true}>
      GPG 密钥内容
    </ParamField>
  </Accordion>

  <Accordion title="PyPI">
    将 Python SDK 发布到 Python Package Index。

    ```yaml title="generators.yml"
    output:
      location: pypi
      package-name: "myorg-api-sdk"
      token: "${PYPI_TOKEN}"
      metadata:
        keywords: ["api", "sdk", "client"]
        documentation-link: "https://docs.myorg.com"
        homepage-link: "https://myorg.com"
    ```

    <ParamField path="location" type="'pypi'" required={true}>
      设置为"pypi"以发布到 PyPI
    </ParamField>

    <ParamField path="url" type="string" required={false}>
      自定义 PyPI 注册表 URL（可选，默认为 PyPI）
    </ParamField>

    <ParamField path="package-name" type="string" required={true}>
      Python 包名称（例如，"myorg-api-sdk"）
    </ParamField>

    <ParamField path="token" type="string" required={false}>
      用于发布的 PyPI 身份验证令牌
    </ParamField>

    <ParamField path="username" type="string" required={false}>
      PyPI 用户名（令牌身份验证的替代方案）
    </ParamField>

    <ParamField path="password" type="string" required={false}>
      PyPI 密码（令牌身份验证的替代方案）
    </ParamField>

    <ParamField path="metadata" type="objecta" required={false}>
      包的额外 PyPI 特定元数据
    </ParamField>

    <ParamField path="metadata.keywords" type="list of string" required={false}>
      用于 PyPI 搜索和发现的包关键字
    </ParamField>

    <ParamField path="metadata.documentation-link" type="string" required={false}>
      包文档链接
    </ParamField>

    <ParamField path="metadata.homepage-link" type="string" required={false}>
      项目主页链接
    </ParamField>
  </Accordion>

  <Accordion title="NuGet">
    将 .NET SDK 发布到 NuGet 存储库。

    ```yaml title="generators.yml"
    output:
      location: nuget
      package-name: "MyOrg.ApiSdk"
      api-key: "${NUGET_API_KEY}"
    ```

    <ParamField path="location" type="'nuget'" required={true}>
      设置为"nuget"以发布到 NuGet
    </ParamField>

    <ParamField path="url" type="string" required={false}>
      自定义 NuGet feed URL（可选，默认为 nuget.org）
    </ParamField>

    <ParamField path="package-name" type="string" required={true}>
      NuGet 包名称（例如，"MyOrg.ApiSdk"）
    </ParamField>

    <ParamField path="api-key" type="string" required={false}>
      用于发布到 feed 的 NuGet API 密钥
    </ParamField>
  </Accordion>

  <Accordion title="RubyGems">
    将 Ruby SDK 发布到 RubyGems 注册表。

    ```yaml title="generators.yml"
    output:
      location: rubygems
      package-name: "myorg_api_sdk"
      api-key: "${RUBYGEMS_API_KEY}"
    ```

    <ParamField path="location" type="'rubygems'" required={true}>
      设置为"rubygems"以发布到 RubyGems
    </ParamField>

    <ParamField path="url" type="string" required={false}>
      自定义 RubyGems 注册表 URL（可选，默认为 rubygems.org）
    </ParamField>

    <ParamField path="package-name" type="string" required={true}>
      Ruby gem 包名称（例如，"myorg\_api\_sdk"）
    </ParamField>

    <ParamField path="api-key" type="string" required={false}>
      用于发布的 RubyGems API 密钥（需要"Push rubygem"权限）
    </ParamField>

    > **注意**: RubyGems API 密钥需要"Push rubygem"权限，理想情况下还需要"index"和"yank rubygem"权限。如果启用了 MFA，请确保 MFA 设置不要求为 API 密钥使用提供 MFA。
  </Accordion>

  <Accordion title="Postman">
    将 API 集合发布到 Postman 工作区。

    ```yaml title="generators.yml"
    output:
      location: postman
      api-key: "${POSTMAN_API_KEY}"
      workspace-id: "12345678-1234-1234-1234-123456789abc"
      collection-id: "87654321-4321-4321-4321-cba987654321"
    ```

    <ParamField path="location" type="'postman'" required={true}>
      设置为"postman"以发布到 Postman
    </ParamField>

    <ParamField path="api-key" type="string" required={true}>
      用于工作区访问的 Postman API 密钥
    </ParamField>

    <ParamField path="workspace-id" type="string" required={true}>
      将发布集合的目标 Postman 工作区 ID
    </ParamField>

    <ParamField path="collection-id" type="string" required={false}>
      要更新的现有集合 ID（如果未指定则创建新集合）
    </ParamField>
  </Accordion>

  <Accordion title="本地文件系统">
    将生成的 SDK 保存到本地文件系统而不是发布。

    ```yaml title="generators.yml"
    output:
      location: local-file-system
      path: "./generated-sdks/typescript"
    ```

    <ParamField path="location" type="'local-file-system'" required={true}>
      设置为"local-file-system"以本地输出
    </ParamField>

    <ParamField path="path" type="string" required={true}>
      生成的文件将保存的本地目录路径
    </ParamField>
  </Accordion>
</AccordionGroup>

#### `github`

使用 `github` 配置指定如何在 GitHub 中生成 SDK。
指定 `mode` 以指定 Fern 如何处理您的代码更改。对于云生成，使用 `repository` 指定 GitHub 存储库。对于[自托管生成](/learn/sdks/deep-dives/self-hosted)，改用 `uri` 和 `token`。

<Note>
  确保在您的目标存储库上安装了 

  [Fern GitHub 应用](https://github.com/apps/fern-api)

  （自托管生成不需要）
</Note>

<AccordionGroup>
  <Accordion title="Release（默认）">
    Fern 生成您的代码，提交到 main 分支，并标记新版本。

    ```yml {6-17}
    groups: 
      ts-sdk:
        generators:
          - name: fernapi/fern-typescript-sdk
          ...
            github: 
              repository: "your-org/your-repo-name"
              mode: "release"
    ```

    <ParamField path="repository" type="string" required={true} toc={true}>
      您在 GitHub 中的存储库名称。
    </ParamField>

    <ParamField path="mode" type="'release'" required={false} toc={true} />

    <ParamField path="branch" type="string" required={false} toc={true}>
      您在 GitHub 中的分支名称。
    </ParamField>

    <ParamField path="license" type="'MIT' | 'Apache-2.0' | 'Custom License Name'" required={false} toc={true}>
      生成的 SDK 的软件许可证。
    </ParamField>

    <ParamField path="reviewers" type="{ teams: list<string>, users: list<string> }" required={false} toc={true}>
      指定哪些团队和用户应审查生成的代码。请参阅[审查者配置](#reviewers-1)。
    </ParamField>
  </Accordion>

  <Accordion title="Pull request（推荐）">
    Fern 生成您的代码，提交到新分支，并打开 PR 进行审查。要发布，您必须合并 PR 并标记 GitHub 版本。

    ```yml {6-8}
    groups: 
      ts-sdk:
        generators:
          - name: fernapi/fern-typescript-sdk
          ...
            github: 
              repository: "your-org/your-repo-name"
              mode: "pull-request"
    ```

    <ParamField path="repository" type="string" required={true} toc={true}>
      您在 GitHub 中的存储库名称。
    </ParamField>

    <ParamField path="mode" type="'pull-request'" required={false} toc={true} />

    <ParamField path="branch" type="string" required={false} toc={true}>
      您在 GitHub 中的分支名称。
    </ParamField>

    <ParamField path="license" type="'MIT' | 'Apache-2.0' | 'Custom License Name'" required={false} toc={true}>
      生成的 SDK 的软件许可证。
    </ParamField>

    <ParamField path="reviewers" type="list of objects" required={false} toc={true}>
      指定哪些团队和用户应审查生成的代码。请参阅[审查者配置](#reviewers-1)。
    </ParamField>
  </Accordion>

  <Accordion title="Push">
    Fern 生成您的代码并将其推送到您指定的分支。

    ```yml {6-8}
    groups: 
      ts-sdk:
        generators:
          - name: fernapi/fern-typescript-sdk
          ...
            github: 
              repository: "your-org/your-repo-name"
              mode: "push"
              branch: "your-branch-name" # `mode: push` 必需
    ```

    <ParamField path="repository" type="string" required={true} toc={true}>
      您在 GitHub 中的存储库名称。
    </ParamField>

    <ParamField path="mode" type="'push'" required={false} toc={true} />

    <ParamField path="branch" type="string" required={true} toc={true}>
      您在 GitHub 中的分支名称。
    </ParamField>

    <ParamField path="license" type="'MIT' | 'Apache-2.0' | 'Custom License Name'" required={false} toc={true}>
      生成的 SDK 的软件许可证。
    </ParamField>

    <ParamField path="reviewers" type="{ teams: list<string>, users: list<string> }" required={false} toc={true}>
      指定哪些团队和用户应审查生成的代码。请参阅[审查者配置](#reviewers-1)。
    </ParamField>
  </Accordion>

  <Accordion title="自托管">
    对于[自托管 SDK 生成](/learn/sdks/deep-dives/self-hosted)，使用 `uri` 和 `token` 而不是 `repository` 配置 `github` 属性。

    ```yml {6-10}
    groups: 
      ts-sdk:
        generators:
          - name: fernapi/fern-typescript-sdk
          ...
            github: 
              uri: "https://github.com/your-org/your-repo-name"
              token: "${GITHUB_TOKEN}"
              mode: "push"
              branch: "main"
    ```

    <ParamField path="uri" type="string" required={true} toc={true}>
      您的 GitHub 存储库的完整 URL（例如，`https://github.com/your-org/your-repo`）。
    </ParamField>

    <ParamField path="token" type="string" required={true} toc={true}>
      具有存储库写入权限的 GitHub 个人访问令牌。使用环境变量引用（例如，`${GITHUB_TOKEN}`）。
    </ParamField>

    <ParamField path="mode" type="'push' | 'pull-request'" required={false} toc={true}>
      如何发布更改：`push` 直接提交到分支，`pull-request` 打开 PR 进行审查。
    </ParamField>

    <ParamField path="branch" type="string" required={false} toc={true}>
      提交或拉取请求的目标分支。
    </ParamField>
  </Accordion>
</AccordionGroup>

#### `metadata`

指定单个 SDK 的元数据。或者，您可以[为所有 SDK 全局配置元数据](#metadata)。

```yml title="generators.yml" {6-10}
groups: 
  ts-sdk:
    generators:
      - name: fernapi/fern-typescript-sdk
      ...
        metadata: 
          package-description: "您的 SDK 描述"
          email: "sdk@example.com"
          reference-url: "https://docs.example.com/sdks"
          license: "MIT"
```

<ParamField path="package-description" type="string" required={false} toc={true}>
  您生成的 SDK 功能及其关键特性的简要描述。这出现在 `package.json` 描述字段和包注册表列表中。
</ParamField>

<ParamField path="email" type="string" required={false} toc={true}>
  包维护者或支持团队的联系电子邮件。
</ParamField>

<ParamField path="reference-url" type="string" required={false} toc={true}>
  指向 SDK 的综合文档、API 参考或入门指南的 URL。
</ParamField>

<ParamField path="author" type="string" required={false} toc={true}>
  创建和维护 SDK 的个人开发者、团队或组织的名称。
</ParamField>

<ParamField path="license" type="'MIT' | 'Apache-2.0' | 'Custom License Name'" required={false} toc={true}>
  生成的 SDK 的软件许可证。
</ParamField>

#### `autorelease`

为单个 SDK 启用或禁用 [Fern Autorelease](/learn/sdks/overview/autorelease)。或者，您可以[为所有 SDK 全局配置自动发布](#autorelease-1)。

```yml title="generators.yml" {6}
groups:
  ts-sdk:
    generators:
      - name: fernapi/fern-typescript-sdk
      ...
        autorelease: true
```

<ParamField path="autorelease" type="boolean" default={false} required={false} toc={true}>
  设置为 `true` 为此生成器启用自动发布，`false` 禁用它。每个生成器的设置覆盖全局 [`autorelease`](#autorelease-1) 配置。
</ParamField>

#### `snippets`

为特定生成器配置代码片段。

```yml title="generators.yml" {6-8}
groups: 
  ts-sdk:
    generators:
      - name: fernapi/fern-typescript-sdk
      ...
        snippets: 
          path: "./snippets"
```

<ParamField path="path" type="string" required={true} toc={true}>
  生成的代码片段文件的路径。
</ParamField>

#### 覆盖 API 身份验证设置

使用 `api` 配置为特定 SDK 覆盖身份验证设置。

<AccordionGroup>
  <Accordion title="单一身份验证方案">
    按名称引用[预定义的身份验证方案](#auth-schemes)。

    ```yml title="generators.yml" {6-7}
    groups: 
      ts-sdk:
        generators:
          - name: fernapi/fern-typescript-sdk
          ...
            api:
              auth: "bearer-token"
    ```

    <ParamField path="auth" type="string | { scheme: string }" required={false} toc={true}>
      要使用的身份验证方案。可以是字符串引用（`"bearer-token"`）或方案对象（`scheme: "bearer-token"`）。
    </ParamField>
  </Accordion>

  <Accordion title="多个身份验证选项">
    允许用户使用多种方法中的任何一种进行身份验证：

    ```yml title="generators.yml" {6-12}
    groups: 
      ts-sdk:
        generators:
          - name: fernapi/fern-typescript-sdk
          ...
            api:
              auth:
                any:
                  - "api-key"
                  - "bearer-token"
                  - scheme: "oauth-flow"
    ```

    <ParamField path="any" type="list<string | { scheme: string }>" required={true} toc={true}>
      用户可以选择任何一种方法的身份验证方案列表。每个项可以是字符串引用（`"api-key"`）或方案对象（`scheme: "api-key"`）。
    </ParamField>
  </Accordion>

  <Accordion title="自定义身份验证方案">
    使用 `auth-schemes` 定义自定义身份验证方案。您为自定义方案定义名称，然后指定身份验证方法（`header`、`basic`、`bearer` 或 `oauth`）。

    ```yml title="generators.yml" {8-12}
    groups: 
      ts-sdk:
        generators:
          - name: fernapi/fern-typescript-sdk
          ...
            api:
              auth-schemes:
                bearer:  # 您的身份验证模式的用户定义名称
                  scheme: "bearer"
                  token:
                    name: "token"
                    env: "BEARER_TOKEN"
    ```

    <AccordionGroup>
      <Accordion title="Header 身份验证">
        Configure authentication using custom HTTP headers, such as API keys or tokens.

        ```yaml
        auth-schemes:
          api-key: # User-defined scheme name
            name: "API Key Authentication"
            header: "X-API-Key"
            type: "string"
            prefix: "ApiKey "
            env: "MY_API_KEY" # SDK will auto-scan this environment variable
        ```

        <ParamField path="header" type="string" required={true}>
          The name of the HTTP header to use for authentication.
        </ParamField>

        <ParamField path="name" type="string" required={false}>
          A descriptive name for this authentication scheme.
        </ParamField>

        <ParamField path="type" type="string" default="string">
          The type of the header value.
        </ParamField>

        <ParamField path="prefix" type="string" required={false}>
          A prefix to prepend to the header value (e.g., `"Bearer "` or `"Token "`).
        </ParamField>

        <ParamField path="env" type="string" required={false}>
          Environment variable name containing the authentication value. When specified, the generated SDK will automatically scan for this environment variable at initialization.
        </ParamField>
      </Accordion>

      <Accordion title="Basic 身份验证">
        Configure HTTP Basic authentication using username and password credentials.

        ```yaml
        auth-schemes:
          basic-auth: # User-defined scheme name
            scheme: basic
            username:
              name: "Username"
              env: "BASIC_AUTH_USERNAME" # SDK will auto-scan this environment variable
            password:
              name: "Password"
              env: "BASIC_AUTH_PASSWORD" # SDK will auto-scan this environment variable
        ```

        <ParamField path="scheme" type="'basic'" required={true}>
          Must be set to `"basic"` for Basic authentication schemes.
        </ParamField>

        <ParamField path="username" type="object" required={false}>
          Configuration for the username credential.
        </ParamField>

        <ParamField path="username.name" type="string" required={false}>
          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"`.
        </ParamField>

        <ParamField path="password" type="object" required={false}>
          Configuration for the password credential.
        </ParamField>

        <ParamField path="password.name" type="string" required={false}>
          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"`.
        </ParamField>

        <ParamField path="username.env, password.env" type="string" required={false}>
          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`.
        </ParamField>
      </Accordion>

      <Accordion title="Bearer Token 身份验证">
        Configure Bearer token authentication for API access.

        ```yaml
        auth-schemes:
          bearer-token: # User-defined scheme name
            scheme: bearer
            token:
              name: "Access Token"
              env: "BEARER_TOKEN" # SDK will auto-scan this environment variable
        ```

        <ParamField path="scheme" type="'bearer'" required={true}>
          Must be set to `"bearer"` for Bearer token authentication schemes.
        </ParamField>

        <ParamField path="token" type="object" required={false}>
          Configuration for the bearer token.
        </ParamField>

        <ParamField path="token.name" type="string" required={false}>
          A descriptive name for the token.
        </ParamField>

        <ParamField path="token.env" type="string" required={false}>
          Environment variable name containing the bearer token. When specified, the generated SDK will automatically scan for this environment variable at initialization.
        </ParamField>
      </Accordion>

      <Accordion title="OAuth Client Credentials">
        <Note>
          For Fern Definition, you can configure OAuth authentication either in `generators.yml` or [directly in your `api.yml` file](/api-definitions/ferndef/authentication#oauth-client-credentials). For OpenAPI, [OAuth must be configured in `generators.yml`](/api-definitions/openapi/authentication#oauth-client-credentials).
        </Note>

        Configure OAuth 2.0 client credentials authentication. Optionally configure a `refresh-token` endpoint for token renewal without re-authentication.

        ```yaml title="generators.yml" maxLines=10
        auth-schemes:
          my-oauth: # User-defined scheme name
            scheme: oauth
            type: client-credentials
            scopes:
              - "read:users"
              - "write:users"
            client-id-env: "OAUTH_CLIENT_ID" # SDK will auto-scan this environment variable
            client-secret-env: "OAUTH_CLIENT_SECRET" # SDK will auto-scan this environment variable
            token-prefix: "Bearer"
            token-header: "Authorization"
            get-token:
              endpoint: "auth.get_token"
              request-properties:
                client-id: "clientId"
                client-secret: "clientSecret"
                scopes: "scope"
              response-properties:
                access-token: "access_token"
                expires-in: "expires_in"
                refresh-token: "refresh_token"
            refresh-token:
              endpoint: "auth.refresh_token"
              request-properties:
                refresh-token: "refreshToken"
              response-properties:
                access-token: "access_token"
                expires-in: "expires_in"
                refresh-token: "refresh_token"
        ```

        <ParamField path="scheme" type="'oauth'" required={true}>
          Must be set to `"oauth"` for OAuth authentication schemes.
        </ParamField>

        <ParamField path="type" type="'client-credentials'" required={true}>
          The OAuth 2.0 grant type. Currently only `"client-credentials"` is supported.
        </ParamField>

        <ParamField path="scopes" type="list of strings" required={false}>
          OAuth scopes to request when obtaining access tokens (e.g., `"read:users"`, `"write:orders"`).
        </ParamField>

        <ParamField path="client-id-env" type="string" required={false}>
          Environment variable name containing the OAuth client ID. When specified, the generated SDK will automatically scan for this environment variable at initialization.
        </ParamField>

        <ParamField path="client-secret-env" type="string" required={false}>
          Environment variable name containing the OAuth client secret. When specified, the generated SDK will automatically scan for this environment variable at initialization.
        </ParamField>

        <ParamField path="token-prefix" type="string" default="Bearer">
          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.
        </ParamField>

        <ParamField path="token-header" type="string" default="Authorization">
          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"`).
        </ParamField>

        ##### `get-token`

        Specifies the endpoint that exchanges client credentials for an access token. This endpoint is called automatically when the SDK client is initialized.

        ```yaml title="generators.yml"
        get-token:
          endpoint: "auth.get_token"
          request-properties:
            client-id: "clientId"
            client-secret: "clientSecret"
          response-properties:
            access-token: "access_token"
            expires-in: "expires_in"
        ```

        <ParamField path="endpoint" type="string" required={true}>
          The endpoint that issues access tokens, such as `'auth.get_token'` or `'POST /oauth/token'`. If your API uses [namespaces](/learn/api-definitions/overview/project-structure#combined-sdks-from-multiple-apis), prefix with the namespace and `::` (e.g., `'payments::POST /oauth/token'`).
        </ParamField>

        <ParamField path="request-properties" type="object" required={false}>
          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`).
        </ParamField>

        <ParamField path="request-properties.client-id" type="string" required={false}>
          The request field name for the client ID in your API (e.g., `"clientId"`, `"client_id"`).
        </ParamField>

        <ParamField path="request-properties.client-secret" type="string" required={false}>
          The request field name for the client secret in your API (e.g., `"clientSecret"`, `"client_secret"`).
        </ParamField>

        <ParamField path="request-properties.scopes" type="string" required={false}>
          The request field name for scopes in your API (e.g., `"scope"`, `"scopes"`).
        </ParamField>

        <ParamField path="response-properties" type="object" required={false}>
          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`).
        </ParamField>

        <ParamField path="response-properties.access-token" type="string" required={false}>
          The response field name for the access token in your API (e.g., `"accessToken"`, `"access_token"`).
        </ParamField>

        <ParamField path="response-properties.expires-in" type="string" required={false}>
          The response field name for token expiration time in seconds (e.g., `"expiresIn"`, `"expires_in"`). When present, the SDK automatically refreshes tokens before expiration.
        </ParamField>

        <ParamField path="refresh-token" type="string" required={false}>
          The response field name for the refresh token in your API (e.g., `"refreshToken"`, `"refresh_token"`). Required if using the `refresh-token` flow.
        </ParamField>

        ##### `refresh-token`

        Specifies the endpoint that exchanges a refresh token for a new access token. When configured, the SDK automatically uses this endpoint to renew expired tokens without re-sending credentials. If not configured, the SDK will re-authenticate using `get-token` when tokens expire.

        ```yaml title="generators.yml"
        refresh-token:
          endpoint: "auth.refresh_token"
          request-properties:
            refresh-token: "refreshToken"
          response-properties:
            access-token: "access_token"
            expires-in: "expires_in"
        ```

        <ParamField path="endpoint" type="string" required={true}>
          The endpoint that refreshes access tokens (e.g., `"POST /oauth/refresh"` or `"auth.refreshToken"`). If your API uses [namespaces](/learn/api-definitions/overview/project-structure#combined-sdks-from-multiple-apis), prefix with the namespace and `::` (e.g., `"payments::POST /oauth/refresh"`).
        </ParamField>

        <ParamField path="request-properties" type="object" required={false}>
          Maps OAuth parameter names to your API's request field names for the refresh flow.
        </ParamField>

        <ParamField path="request-properties.refresh-token" type="string" required={true}>
          The request field name for the refresh token in your API (e.g., `"refreshToken"`, `"refresh_token"`).
        </ParamField>

        <ParamField path="response-properties" type="object" required={false}>
          Maps your API's refresh response field names to OAuth standard names.
        </ParamField>

        <ParamField path="response-properties.access-token" type="string" required={false}>
          The response field name for the new access token (e.g., `"accessToken"`, `"access_token"`).
        </ParamField>

        <ParamField path="response-properties.expires-in" type="string" required={false}>
          The response field name for the new token's expiration time in seconds (e.g., `"expiresIn"`, `"expires_in"`).
        </ParamField>

        <ParamField path="response-properties.refresh-token" type="string" required={false}>
          The response field name if your API issues a new refresh token with each refresh (token rotation).
        </ParamField>
      </Accordion>
    </AccordionGroup>
  </Accordion>
</AccordionGroup>

### `reviewers`

为所有 SDK 全局设置代码审查者。或者，您可以[为单个 SDK 配置审查者](#reviewers)。

```yaml title="generators.yml"
reviewers:
  teams:
    - name: "sdk-team"
    - name: "api-team"
  users:
    - name: "john-doe"
    - name: "jane-smith"
```

<ParamField path="teams" type="list of strings" required={false} toc={true}>
  GitHub team names that should review generated code.
</ParamField>

<ParamField path="users" type="list of strings" required={false} toc={true}>
  GitHub users that should review generated code.
</ParamField>

<ParamField path="teams.name" type="string" required={true} toc={true}>
  Name of a GitHub team.
</ParamField>

<ParamField path="users.name" type="string" required={true} toc={true}>
  Name of a GitHub user.
</ParamField>