同步您的 OpenAPI 规范 | Fern Documentation

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

设置

配置源 URL

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

generators.yml

1  api:
2    specs: 
3      - openapi: .path/to/openapi.json               # 定义文件
4        overrides: .path/to-openapi-overrides.yml    # 覆盖文件
5        origin: https://api.example.com/openapi.json # 获取最新规范的 URL

添加 GitHub Action

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

.github/workflows/sync-openapi.yml

1 name: Sync OpenAPI Specs # 可以自定义
2 on:                               # 可以配置其他自定义触发器
3   workflow_dispatch:              # 手动触发
4   push:                                          
5     branches:
6       - main                      # 推送到主分支时触发
7   schedule:
8     - cron: '0 3 * * *'           # 每日 UTC 时间凌晨 3:00
9 jobs:
10 update-from-source:
11   runs-on: ubuntu-latest
12   steps:
13     - uses: actions/checkout@v4
14       with:
15         token: ${{ secrets.OPENAPI_SYNC_TOKEN }}
16     - name: Update API with Fern
17       uses: fern-api/sync-openapi@v2
18       with:
19         update_from_source: true
20         token: ${{ secrets.OPENAPI_SYNC_TOKEN }}
21         branch: 'update-api'
22         auto_merge: false
23         add_timestamp: true

创建 GitHub 令牌

生成一个细粒度个人访问令牌，为您的仓库授予 Contents 和 Pull requests 读写权限。

添加到仓库密钥

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

这将创建包含任何 API 规范更新的每日拉取请求。要更改频率，请修改 cron 计划（参见 GitHub 的计划语法）。

其他用例

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