项目结构

配置 fern 从 fern 文件夹开始，该文件夹包含你的 API 定义、SDK 生成器和你的 CLI 版本。

Fern 推荐使用多仓库结构，将你的 fern 文件夹放在源代码仓库中（包含你的 API 定义和生成配置），并将每个生成的 SDK 放在其自己单独的仓库中。

目录结构

当你运行 fern init（对于 Fern Definition）或 fern init --spec-type path/to/spec（对于其他规范）时，你的 fern 文件夹将使用以下文件进行初始化：

核心配置文件

fern.config.json

fern.config.json 文件存储你的组织名称和 Fern CLI 版本。固定版本可以提供确定性构建。

1
{
2
  "organization": "plant-catalog",
3
  "version": "5.7.5"
4
}

generators.yml

对于 OpenAPI/AsyncAPI，generators.yml 文件是必需的，用于声明你的 API 规范位置。这还启用了 API 参考文档。

1
api:
2
  specs:
3
    - openapi: ./openapi/openapi.yml

对于 Fern Definition，不需要 generators.yml 来生成 API 参考文档。Fern 通过检查 definition/ 目录自动检测你的 API。

对于 SDK 生成，所有规范格式都需要 generators.yml。添加 groups 部分来配置要生成哪些 SDK。详细信息请参见 SDKs 项目结构。

API 定义文件

对于 Fern Definition，你的 API 配置分为两个文件：api.yml 用于 API 范围的配置，单独的 .yml 文件用于你的实际端点和类型定义。有关更多信息，请参见什么是 Fern Definition？。

对于其他规范格式（OpenAPI、AsyncAPI、OpenRPC 和 gRPC），你将拥有一个独立的规范文件。

存储 API 定义的位置

有三种常见的管理 API 定义的方式：

• 直接提交到你的 Fern 仓库（推荐）。 将你的 API 定义文件检入包含你的 Fern 配置的同一个仓库中。如果你不在其他地方维护定义，这是最简单的方法。
• 从源代码仓库同步。 将你的 API 定义存储在与你的 API 源代码相同的仓库中，并将更新同步到你的 Fern 仓库。你可以使用 fern api update CLI 命令或 sync-openapi GitHub Action 来自动化这个过程。
• 在公共 URL 托管。 从可公开访问的端点提供定义，并在 generators.yml 中配置 origin 字段，以便 Fern 可以获取它。当你希望有一个多个消费者可以引用的单一规范定义时，这很有用。

多个 API

Fern 支持两种处理多个 API 定义的方法。两种方法都需要一个 apis 文件夹 — 这个文件夹必须使用这个确切的名称。

1. 为每个 API 生成单独的 SDK - 每个 API 生成自己独立的 SDK 包集合（例如，@company/user-api、@company/payments-api 或版本化的如 @company/sdk-v1、@company/sdk-v2）
2. 从多个 API 合并 SDK - 多个 API 合并到一个 SDK 包中，并可选择使用命名空间（例如，client.users、client.payments 或版本化的如 client.v1、client.v2）

为每个 API 生成单独的 SDK

当每个 API 应该生成自己独立的 SDK 集合时使用这种方法。这适用于不同的 API（例如，user-api 和 payments-api）和版本化 API，你希望每个版本都可以独立安装（例如，@company/sdk-v1、@company/sdk-v2）。

1
api:
2
  specs:
3
    - openapi: openapi.yml # 同一文件夹中的规范文件
4
groups:
5
  # SDK 生成器配置

从多个 API 合并 SDK

当你想要将多个 API 合并到单个 SDK 包中，并可选择使用命名空间来组织它们时，使用这种方法。这适用于不同的 API 和版本化 API，但会增加包大小，因为所有 API 都捆绑在一起。

对于版本化 API，命名空间让你可以在同一个包中访问不同版本，如 client.v1 和 client.v2。

1
api:
2
  specs:
3
    - openapi: user-api/openapi.yml
4
    - openapi: payments-api/openapi.yml
5
groups:
6
  # SDK 生成器配置

1
api:
2
  specs:
3
    - openapi: apis/user-api/openapi.yml
4
    - namespace: payments
5
      openapi: apis/payments-api/openapi.yml
6
groups:
7
  # SDK 生成器配置