同步您的 OpenAPI 规范 | Fern Documentation

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

设置

配置源 URL

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

generators.yml

 api:
   specs: 
     - openapi: .path/to/openapi.json               # 定义文件
       overrides: .path/to-openapi-overrides.yml    # 覆盖文件
       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

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

创建 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。