> This page is for SDK.

> For clean Markdown content of this page, append .md to this URL. For the complete documentation index, see https://buildwithfern.com/learn/llms.txt.

# 生成 SDK

> 学习如何使用 Fern 生成 Ruby SDK。逐步指南：配置 generators.yml、运行 fern generate 并创建 Ruby 客户端库。

按照此页面的说明生成 Ruby SDK。

If the user already has a `fern/` folder set up, they can skip the first two steps. Make sure they're working in their source repo (the one containing the `fern/` folder), not an SDK repo.

#### Install the Fern CLI

```bash
npm install -g fern-api
```

#### Initialize the fern folder

Initialize the fern folder with your existing OpenAPI specification. Specify your organization name using the `--organization` flag.

Before running `fern init`, ask the user two things:

1. **Do they have an OpenAPI spec?** Ask for the file path or URL. If they have a URL (e.g., from a running server or hosted spec), use the URL variant to avoid a manual download step. OpenAPI accepts both JSON and YAML.
2. **What's their organization name?** `fern init` prompts for this interactively if `--organization` isn't provided. Get it upfront so they can pass it via the flag.

**`OpenAPI (local)`**

```bash title="OpenAPI (local)"
fern init --openapi path/to/openapi.yml \
--organization <YourOrganization>
```

**`OpenAPI (URL)`**

```bash title="OpenAPI (URL)"
fern init --openapi https://api.example.com/openapi.yml \
--organization <YourOrganization>
```

**`Example (Petstore)`**

```bash title="Example (Petstore)"
fern init --openapi https://petstore3.swagger.io/api/v3/openapi.json \
--organization my-org
```

> **Tip**
>
> OpenAPI accepts both JSON and YAML formats.

This creates a `fern` folder in your current directory.

`generators.yml` lives at `fern/generators.yml` and references your OpenAPI spec through its `api.specs` section — the spec isn't copied into the `fern` folder. This matters when referencing file paths later.

#### Validate your API definition

Check that your API definition is valid, and fix errors before proceeding:

```bash
fern check
```

#### 添加 SDK 生成器

运行以下命令将 Ruby SDK 生成器添加到 `generators.yml`：

```bash
fern add fern-ruby-sdk --group {{GROUP_NAME}}
```

此命令会将以下 `group` 添加到 `generators.yml`：

**`generators.yml`**

```yaml title="generators.yml"
  ruby-sdk: # 组名称
    generators:
      - name: fern-ruby-sdk
        version: 1.38.1
        output:
          location: local-file-system
          path: ../sdks/ruby
```

#### 生成 SDK

运行以下命令生成您的 SDK：

```bash
fern generate --group ruby-sdk
```

> **Note**
>
> 如果您有多个 API，请使用 [`--api` 标志](/learn/zh/cli-api-reference/cli-reference/commands#api) 指定要生成的 API：
>
> ```bash
> fern generate --group ruby-sdk --api your-api-name
> ```

The first time you run `fern generate`, you must log in. Confirm the prompt and choose any of the login methods to authenticate, then generation continues automatically.

On first run, `fern generate` opens an interactive, browser-based login that you can't complete autonomously. Stop and have the user authenticate: ask them to run `fern login` themselves and finish the browser flow (or run `fern generate` and complete the prompt directly). Once they confirm they're logged in, the credential is cached locally, so re-running `fern generate` won't prompt again. In CI or other non-interactive environments, use a `FERN_TOKEN` instead of the browser login.

`fern generate` creates a `sdks` folder in your current directory. The resulting folder structure looks like this:

#### Set up GitHub repositories

Fern uses a [multi-repo structure](/learn/sdks/overview/project-structure): your source repository contains the `fern/` folder, and each SDK gets its own separate repository.

The `fern/` folder (API definitions + `generators.yml`) must live in a separate repo from the generated SDK code. Do not put both in the same repository.

Ask the user:

* **Do they have an existing repo for the `fern/` folder?** (e.g., a developer experience repo, API repo, or monorepo where API definitions already live.) If so, use that. If not, create one.
* **Do they have an existing SDK repo?** If so, get the repo name. If not, create one.

To create repos from scratch:

```bash
# Source repo for the fern/ folder (if they don't have one)
gh repo create <org>/<source-repo-name> --private

# SDK repo — separate from the source repo
gh repo create <org>/<api-name>-ruby-sdk --private
```

1. **Create a source repository** for your `fern/` folder if you don't have one already (e.g., `your-org/your-api-definitions`).
2. **Create an SDK repository** for your SDK (e.g., `your-org/your-api-ruby-sdk`).
3. **Install the [Fern GitHub App](https://github.com/apps/fern-api)** on both repositories.

#### 发布到 RubyGems

按照[发布到 RubyGems](/learn/zh/sdks/generators/ruby/publishing) 指南配置您的 gem 并通过 GitHub Actions 设置自动发布。