同步你的 AsyncAPI 规范 | Fern Documentation

保持你的 AsyncAPI 规范与代码库同步对于维护准确的 SDK 和文档至关重要。Fern 提供了几种自动化选项来简化这个过程。

GitHub Actions

使用 Fern 的 GitHub Action 在你的 AsyncAPI 规范发生变更时自动更新 SDK 和文档：

.github/workflows/fern.yml

1 name: Fern
2 
3 on:
4   push:
5     branches:
6       - main
7   pull_request:
8     branches:
9       - main
10 
11 jobs:
12   fern-check:
13     runs-on: ubuntu-latest
14     steps:
15       - name: Checkout repo
16         uses: actions/checkout@v4
17         
18       - name: Check AsyncAPI spec
19         uses: fern-api/action@v0
20         with:
21           command: check
22         env:
23           FERN_TOKEN: ${{ secrets.FERN_TOKEN }}
24 
25   fern-generate:
26     runs-on: ubuntu-latest
27     if: github.event_name == 'push' && github.ref == 'refs/heads/main'
28     steps:
29       - name: Checkout repo
30         uses: actions/checkout@v4
31         
32       - name: Generate SDKs and docs
33         uses: fern-api/action@v0
34         with:
35           command: generate
36         env:
37           FERN_TOKEN: ${{ secrets.FERN_TOKEN }}

Webhook 集成

设置 webhook 以在 AsyncAPI 规范更新时触发 SDK 生成：

generators.yml

1 api:
2   specs:
3     - spec: asyncapi.yml
4   github:
5     repository: your-org/your-repo
6   webhooks:
7     - url: https://your-api.com/webhooks/fern
8       events: [generate]
9   generators:
10     - name: fernapi/fern-typescript-sdk
11       version: 0.8.8
12       output:
13         location: npm
14         package-name: "@your-org/sdk"

从源自动同步

配置 Fern 自动从各种源拉取你的 AsyncAPI 规范：

从 URL

generators.yml

1 api:
2   specs:
3     - spec: https://api.yourcompany.com/asyncapi.yml
4       auto-sync: true
5   generators:
6     - name: fernapi/fern-typescript-sdk
7       version: 0.8.8

从 git 仓库

generators.yml

1 api:
2   specs:
3     - spec:
4         git:
5           repository: https://github.com/your-org/api-specs
6           path: asyncapi/api.yml
7           branch: main
8   generators:
9     - name: fernapi/fern-typescript-sdk
10       version: 0.8.8

CI/CD 集成

CircleCI

.circleci/config.yml

1 version: 2.1
2 
3 orbs:
4   fern: fernapi/fern@1.0
5 
6 workflows:
7   version: 2
8   build-and-test:
9     jobs:
10       - build
11       - test:
12           requires:
13             - build
14       - fern/generate:
15           requires:
16             - test
17           filters:
18             branches:
19               only: main
20           context:
21             - fern-context

GitLab CI

.gitlab-ci.yml

1 stages:
2   - build
3   - test
4   - generate
5 
6 variables:
7   FERN_TOKEN: $FERN_TOKEN
8 
9 build:
10   stage: build
11   script:
12     - echo "Building application..."
13 
14 generate-sdks:
15   stage: generate
16   image: fernapi/fern:latest
17   script:
18     - fern generate
19   only:
20     - main

定时更新

设置定时更新以确保你的 SDK 保持最新：

.github/workflows/scheduled-update.yml

1 name: Scheduled AsyncAPI Update
2 
3 on:
4   schedule:
5     - cron: '0 2 * * 1'  # Every Monday at 2 AM UTC
6   workflow_dispatch:
7 
8 jobs:
9   update-specs:
10     runs-on: ubuntu-latest
11     steps:
12       - name: Checkout repo
13         uses: actions/checkout@v4
14         
15       - name: Update AsyncAPI specs
16         run: |
17           curl -o fern/asyncapi/asyncapi.yml https://api.yourcompany.com/asyncapi.yml
18           
19       - name: Generate with latest spec
20         uses: fern-api/action@v0
21         with:
22           command: generate
23         env:
24           FERN_TOKEN: ${{ secrets.FERN_TOKEN }}

监控变更

跟踪你的 AsyncAPI 规范的变更：

generators.yml

1 api:
2   specs:
3     - spec: asyncapi.yml
4   change-detection:
5     enabled: true
6     breaking-changes: error
7     notifications:
8       slack: ${{ secrets.SLACK_WEBHOOK }}
9       email: team@yourcompany.com
10   generators:
11     - name: fernapi/fern-typescript-sdk
12       version: 0.8.8

这确保了对你的 AsyncAPI 规范的任何破坏性变更都会被检测到，并且在变更传播到你的 SDK 和文档之前通知相应的团队成员。