> 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.eyJpc3MiOiJmZXJuLWRvY3M6YnVpbGR3aXRoZmVybi5jb20iLCJqdGkiOiIzOWY1YWYyMi1jNzk2LTQ4MDAtOGExOC01MzZjY2NiZDU4ZTgiLCJleHAiOjE3NzgzNDY0NjQsImlhdCI6MTc3ODM0NjE2NH0.cthlG-_VGUMPApMOrrlR_KUtadSirWSJqwr6j7GDA6A
>
> 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.

# api.yml 配置文件

> 使用 Fern Definition 格式时，api.yml 文件包含通用 API 配置。

`fern/` 文件夹中有一个名为 `api.yml` 的特殊文件，其中包含所有 API 级别的配置。

```bash {5}
fern/
├─ fern.config.json
├─ generators.yml
└─ definition/
  ├─ api.yml
  ├─ pet.yml
  ├─ store.yml
  └─ user.yml
```

## API 名称

此名称用于在您的组织中唯一标识您的 API。如果您只有一个 API，那么 `api` 是一个合适的名称。

<CodeBlock title="api.yml">
  ```yaml
  name: api
  ```
</CodeBlock>

## API 描述

您可以定义顶级 API 描述。此描述将出现在 OpenAPI 规范和 Postman 集合中。

<CodeBlock title="api.yml">
  ```yaml {2-4}
  name: api
  docs: | 
    ## Header
    This API provides access to...
  ```
</CodeBlock>

## API 版本

您可以定义基于请求头的 API 版本控制方案，例如 `X-API-Version`。支持的版本和默认值的指定方式如下：

<CodeBlock title="api.yml">
  ```yaml
  version:
    header: X-API-Version
    default: "2.0.0"
    values:
      - "1.0.0"
      - "2.0.0"
      - "latest"
  ```
</CodeBlock>