> 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.eyJpc3MiOiJmZXJuLWRvY3M6YnVpbGR3aXRoZmVybi5jb20iLCJqdGkiOiJiNzAyOTI5Yy1hMDgwLTRjMzUtOTQzZS01YTAyYTUwOWNjNTUiLCJleHAiOjE3NzgzNDYwMTIsImlhdCI6MTc3ODM0NTcxMn0.zMoISUFxC7rEvm0VDn-KIKdHmTWUu3TXOzt3Ikfc0IE
>
> 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 Definition？

> Fern Definition 是用于 API 规范的 YAML 格式。在一个统一的真实数据源中定义您的 REST API 端点、数据模型和错误。

Fern Definition 是一组 YAML 文件，是您 API 的单一真实数据源。您可以将 Fern Definition 提交到您的代码库中，其中描述了您的 API 请求、响应、模型、路径、方法、错误和身份验证方案。

<Note>
  想要使用 OpenAPI？没问题，我们[同样支持](/learn/api-definitions/overview/what-is-an-api-definition#openapi-swagger)
</Note>

## Fern Definition 结构

要初始化一个 Fern Definition，只需运行：

```sh
npm install -g fern-api
fern init
```

这将在您的项目中创建以下文件夹结构：

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

    <File name="generators.yml" comment="您正在使用的生成器" />

    <Folder name="definition" defaultOpen>
      <File name="api.yml" comment="API 级配置" />

      <File name="imdb.yml" comment="端点、类型和错误" />
    </Folder>
  </Folder>
</Files>

## Definition 文件

每个 Fern Definition 文件可以定义：

* **[自定义类型](/learn/api-definitions/ferndef/types)**。使用**自定义类型**来构建您的数据模型。
* **[端点](/learn/api-definitions/ferndef/endpoints/overview)**。一个**服务**是一组相关的 REST 端点。
* **[错误](/learn/api-definitions/ferndef/errors)**。一个**错误**代表端点的失败（非 200）响应。
* **[导入](/learn/api-definitions/ferndef/imports)**。使用**导入**在文件之间共享类型。

```yml imdb.yml maxLines=0
service:
  auth: false
  base-path: /movies
  endpoints:
    createMovie:
      docs: Add a movie to the database
      method: POST
      path: /create-movie
      request: CreateMovieRequest
      response: MovieId

    getMovie:
      method: GET
      path: /{movieId}
      path-parameters:
        movieId: MovieId
      response: Movie
      errors:
        - NotFoundError
        - UnauthorizedError

types:
  Movie:
    properties:
      title: string
      rating:
        type: double
        docs: The rating scale from one to five stars
      id:
        type: MovieId
        docs: The unique identifier for a movie

  CreateMovieRequest:
    properties:
      title: string
      rating: double

errors:
  NotFoundError:
    http:
      statusCode: 404
    type:
      properties:
        id: MovieId

  UnauthorizedError:
    http:
      statusCode: 401
```

## 为什么要使用另一种格式？

Google 构建了 gRPC。Amazon 构建了 Smithy。Facebook 构建了 GraphQL。Palantir 构建了 Conjure。这些公司拒绝了 OpenAPI，而选择了更简洁的 API Definition Language。

我们构建 Fern 是为了将这种设计产品化，并使所有软件公司都能使用它。

<Info>
  尽管这是描述 API 的不同格式，**但您永远不会被锁定在 Fern 中**。将您的 [Fern Definition 转换为 OpenAPI](/learn/api-definitions/ferndef/export-openapi) 很容易。
</Info>