> 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.eyJpc3MiOiJmZXJuLWRvY3M6YnVpbGR3aXRoZmVybi5jb20iLCJqdGkiOiJlZjFkYTIxZS0yMGY4LTQzZjQtYWEzYi1hOGU0MjY3OWZlYjAiLCJleHAiOjE3ODA1NTc3MDksImlhdCI6MTc4MDU1NzQwOX0.YK0tRGfdkuXarQlXQSFaBQjp0Y2dbE7ke9sXHTGI0iQ
>
> 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.

# 同步您的 OpenAPI 规范

使用 [sync-openapi GitHub Action](https://github.com/fern-api/sync-openapi) 自动从公开可用的 URL 将最新的 OpenAPI 规范拉取到您的 fern 文件夹中。这样可以让您提交的规范与实时 API 保持同步，无需手动更新。

## 设置

在您的 `generators.yml` 中添加 `origin` 字段，指定您的 OpenAPI 规范托管位置：

```yml title="generators.yml"
 api:
   specs: 
     - openapi: .path/to/openapi.json               # 定义文件
       overrides: .path/to-openapi-overrides.yml    # 覆盖文件
       origin: https://api.example.com/openapi.json # 获取最新规范的 URL
```

在您的仓库中创建 `.github/workflows/sync-openapi.yml`。此操作使用 [`fern api update`](/cli-api-reference/cli-reference/commands#fern-api-update) 从您的 `generators.yml` 文件中的 `origin` 字段拉取最新版本的 OpenAPI 规范。

```yml title=".github/workflows/sync-openapi.yml"
name: Sync OpenAPI Specs # 可以自定义
on:                               # 可以配置其他自定义触发器
  workflow_dispatch:              # 手动触发
  push:                                          
    branches:
      - main                      # 推送到主分支时触发
  schedule:
    - cron: '0 3 * * *'           # 每日 UTC 时间凌晨 3:00
jobs:
update-from-source:
  runs-on: ubuntu-latest
  steps:
    - uses: actions/checkout@v4
      with:
        token: ${{ secrets.OPENAPI_SYNC_TOKEN }}
    - name: Update API with Fern
      uses: fern-api/sync-openapi@v2
      with:
        update_from_source: true
        token: ${{ secrets.OPENAPI_SYNC_TOKEN }}
        branch: 'update-api'
        auto_merge: false
        add_timestamp: true
```

生成一个 [细粒度个人访问令牌](https://github.com/settings/personal-access-tokens)，为您的仓库授予 **Contents** 和 **Pull requests** 读写权限。

在您的仓库中，转到 `Settings > Secrets and variables > Actions`。点击 **New repository secret**，将其命名为 `OPENAPI_SYNC_TOKEN`，粘贴您的令牌，然后点击 **Add secret**。

这将创建包含任何 API 规范更新的每日拉取请求。要更改频率，请修改 `cron` 计划（参见 GitHub 的 [计划语法](https://docs.github.com/en/actions/reference/events-that-trigger-workflows#schedule)）。

## 其他用例

如果您的 OpenAPI 规范位于不同的仓库中（而不是在公共 URL），您可以使用显式文件映射将其同步到您的 Fern 文件夹。有关此操作和其他高级配置，请参见 [sync-openapi GitHub Action README](https://github.com/fern-api/sync-openapi)。