> 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.eyJpc3MiOiJmZXJuLWRvY3M6YnVpbGR3aXRoZmVybi5jb20iLCJqdGkiOiJmYjZjOTkwNi02YTVhLTQ0NWUtYWJjOS1kZWU0NmYwZDI4NWYiLCJleHAiOjE3ODA1NjA0MzMsImlhdCI6MTc4MDU2MDEzM30.FnlQwG6vmCE5W_lwRsNihCZ5x4IwzqmOxNnacAw6QtI
>
> 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.

# OpenAPI generators.yml 参考

> 在 generators.yml 文件中配置 OpenAPI 规范的参考指南

`generators.yml` 文件有两个作用：它在 `api.specs` 部分声明你的 OpenAPI 规范位置，并在可选的 `groups` 部分配置 SDK 生成。

这里声明的 API 可以通过 `docs.yml` 在你的文档中渲染。请参阅[生成你的 API 参考文档](/learn/docs/api-references/generate-api-ref)。

```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
```

OpenAPI 规范文件的路径。

用于拉取更新的 API 定义源 URL。有关如何设置自动同步的说明，请参阅 [同步您的 OpenAPI 规范](/learn/api-definitions/openapi/sync-your-open-api-specification)。

[OpenAPI Overlay](/learn/api-definitions/openapi/overlays) 文件的路径。Overlay 遵循 [OpenAPI Overlay 规范](https://spec.openapis.org/overlay/v1.0.0.html)，是自定义 OpenAPI 规范的推荐方法。

OpenAPI [覆盖](/learn/api-definitions/openapi/overrides) 文件的路径，或按顺序应用的多个覆盖文件路径列表。建议使用 `overlays` 来实现基于标准的方法。

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

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

规范的命名空间。用于配置 [包含多个 API 版本的单个包](/api-definitions/overview/project-structure#option-2-namespace-based-versioning)。

此单独规范的 OpenAPI 特定生成设置。要在所有 OpenAPI 规范中应用相同的设置，请改用全局 [`api.settings`](/learn/sdks/reference/generators-yml#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 参考文档中包含的端点 [基于其路径](/learn/api-definitions/openapi/extensions/audiences#path-based-filtering)。

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

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

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

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

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

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

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

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

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

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

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