项目结构

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

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

目录结构

当您运行 fern init --spec-type path/to/spec 时，您的 fern 文件夹将使用以下文件进行初始化：

核心配置文件

fern.config.json

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

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

generators.yml

generators.yml 文件声明您的 API 规范位置。这还启用了API 参考文档。

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

对于 SDK 生成，需要 generators.yml 文件。添加 groups 部分来配置要生成哪些 SDK。有关详细信息，请参阅 SDK 项目结构。

API 定义文件

对于 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 生成器配置