> 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.eyJpc3MiOiJmZXJuLWRvY3M6YnVpbGR3aXRoZmVybi5jb20iLCJqdGkiOiJhODQyNmM0YS1hNDk1LTRjYTUtODgyZS02NzdjYzNjOTRkNTQiLCJleHAiOjE3NzgzNjQwMjAsImlhdCI6MTc3ODM2MzcyMH0.xmQ3SeIshoQp0qtoZ0z05MngeNBxF90Ut2a0Tm-M0Pk
>
> 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.

# 项目结构

> 学习如何使用 Fern 构建 SDK 项目结构。设置多仓库架构、配置 generators.yml 并组织 API 定义。

在使用 Fern 生成 SDK 之前，需要设置合适的 GitHub 仓库结构来存放 API 定义和 SDK 代码，使您和用户都能直观地访问、维护和更新代码。

## 仓库架构

Fern 推荐使用多仓库结构，包含：

* **源仓库** 包含 API 定义和 SDK 生成配置
* **SDK 仓库** 为每个 SDK（TypeScript、Python、Go 等）分别创建仓库

<Files>
  <Folder name="company-repo" defaultOpen comment="源仓库">
    <Folder name=".github" defaultOpen>
      <Folder name="workflows" comment="所有 SDK 的发布工作流" />
    </Folder>

    <Folder name="fern" defaultOpen>
      <File name="fern.config.json" comment="根级配置" />

      <File name="generators.yml" comment="引用 SDK 仓库" />

      <Folder name="definition">
        <File name="overrides.yml" comment="可选的覆盖文件" />

        <File name="api.yml" comment="您的 API 定义" />
      </Folder>
    </Folder>
  </Folder>

  <Folder name="typescript-sdk-repo" comment="SDK 仓库">
    <Folder name=".github">
      <Folder name="workflows" comment="由 Fern 生成" />
    </Folder>

    <Folder name="scripts" />

    <Folder name="src" />

    <Folder name="tests" />

    <File name=".fernignore" comment="Fern 不应修改的文件（自定义代码）" />
  </Folder>

  <Folder name="python-sdk-repo" comment="SDK 仓库" />

  <Folder name="go-sdk-repo" comment="SDK 仓库" />
</Files>

这种分离结构允许您集中管理 API 定义，同时将每个 SDK 保存在独立的仓库中，便于独立版本控制和分发。

<Info title="示例">
  查看 Cohere 的 [fern 文件夹](https://github.com/cohere-ai/cohere-developer-experience/tree/23d6c541a01eb6b54dd9bb3588c805bb0e307713/fern) 以及 [TypeScript](https://github.com/cohere-ai/cohere-typescript) 和 [Python](https://github.com/cohere-ai/cohere-python) SDK 仓库。
</Info>

## 核心配置文件

源仓库包含一个 `fern/` 文件夹，其中包含 API 定义和顶级 `generators.yml` 文件。

### `fern.config.json`

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

```json title="fern.config.json"
{
  "organization": "plant-catalog",
  "version": "5.7.5"
}
```

<Info>
  在使用本地安装的 CLI 时，将 `version` 设置为 `"*"`。有关详细信息，请参见 [本地安装 Fern CLI](/cli-api-reference/cli-reference/overview#install-fern-cli-locally)。
</Info>

### `generators.yml`

`generators.yml` 文件在 `groups` 部分配置 SDK 生成。对于 OpenAPI/AsyncAPI，您还必须在 `api.specs` 部分声明 API 规范位置。

<Tabs>
  <Tab title="OpenAPI/AsyncAPI">
    ```yaml title="generators.yml"
    # API 声明（OpenAPI/AsyncAPI 必需）
    api:
      specs:
        - openapi: ./openapi/openapi.yml

    # SDK 生成
    groups:
      ts-sdk:
        generators:
          - name: fernapi/fern-typescript-sdk
            version: 3.69.0
            github:
              repository: your-organization/typescript-sdk-repo

      python-sdk:
        generators:
          - name: fernapi/fern-python-sdk
            version: 5.9.1
            github:
              repository: your-organization/python-sdk-repo
    ```
  </Tab>

  <Tab title="Fern Definition">
    对于 Fern Definition，不需要 `api` 部分。Fern 会自动检测 `definition/` 目录中的 API。

    ```yaml title="generators.yml"
    groups:
      ts-sdk:
        generators:
          - name: fernapi/fern-typescript-sdk
            version: 3.69.0
            github:
              repository: your-organization/typescript-sdk-repo

      python-sdk:
        generators:
          - name: fernapi/fern-python-sdk
            version: 5.9.1
            github:
              repository: your-organization/python-sdk-repo
    ```
  </Tab>
</Tabs>

<Info title="示例">
  查看 Cohere 的 [`generators.yml` 文件](https://github.com/cohere-ai/cohere-developer-experience/blob/23d6c541a01eb6b54dd9bb3588c805bb0e307713/fern/apis/sdks/generators.yml) 和 Vapi 的 [`generators.yml` 文件](https://github.com/VapiAI/docs/blob/9c674c2b16ba03e864e26673c5290c88048c9a7a/fern/apis/api/generators.yml)。
</Info>

完整的配置选项请参见 [`generators.yml` 参考页面](/sdks/reference/generators-yml)。

### API 定义文件

有关组织 API 定义文件和处理多个 API 的详细信息，请参见 [项目结构（API 定义）](/api-definitions/overview/project-structure)。