|
1 | 1 | --- |
2 | | -title: Automatically Update |
| 2 | +title: Sync your OpenAPI Specification |
3 | 3 | subtitle: Pull your latest OpenAPI Specification into your Fern Folder automatically. |
4 | 4 | --- |
5 | 5 |
|
6 | | -If you host your OpenAPI Specification at a publically available URL, you can have Fern programmatically fetch the latest spec on a preconfigured cadence. By default, this will be done every day and open a new PR on the GitHub repo that contains your Fern Folder. This feature requires installation of the [Fern GitHub App](https://github.com/apps/fern-api). |
7 | | - |
8 | | -```yml title="generators.yml" |
9 | | -api: |
10 | | - path: openapi/openapi.json |
11 | | - origin: https://example.com/openapi.json |
| 6 | +If you host your OpenAPI Specification at a publicly available URL, you can have Fern programmatically fetch the latest spec on a preconfigured cadence through the [sync-openapi GitHub Action](https://github.com/fern-api/sync-openapi). This ensures your committed OpenAPI spec stays up to date with your live API. |
| 7 | +## Setup |
| 8 | +<Steps> |
| 9 | + <Step title="Configure the origin URL"> |
| 10 | + Add the origin field to your generators.yml to specify where your OpenAPI spec is hosted: |
| 11 | + ```yml title="generators.yml" |
| 12 | + api: |
| 13 | + path: openapi/openapi.json |
| 14 | + origin: https://api.example.com/openapi.json |
| 15 | + ``` |
| 16 | + </Step> |
| 17 | + <Step title="Add the GitHub Action"> |
| 18 | + Create `.github/workflows/sync-openapi.yml` in your repository: |
| 19 | + ```yml |
| 20 | + name: Sync OpenAPI Specs # can be customized |
| 21 | + on: # additional custom triggers can be configured |
| 22 | + workflow_dispatch: # manual dispatch |
| 23 | + push: |
| 24 | + branches: |
| 25 | + - main # on push to main |
| 26 | + schedule: |
| 27 | + - cron: '0 3 * * *' # everyday at 3:00 AM UTC |
| 28 | + jobs: |
| 29 | + update-from-source: |
| 30 | + runs-on: ubuntu-latest |
| 31 | + steps: |
| 32 | + - uses: actions/checkout@v4 |
| 33 | + with: |
| 34 | + token: ${{ secrets.OPENAPI_SYNC_TOKEN }} |
| 35 | + - name: Update API with Fern |
| 36 | + uses: fern-api/sync-openapi@v2 |
| 37 | + with: |
| 38 | + update_from_source: true |
| 39 | + token: ${{ secrets.OPENAPI_SYNC_TOKEN }} |
| 40 | + branch: 'update-api' |
| 41 | + auto_merge: false |
| 42 | + add_timestamp: true |
12 | 43 | ``` |
| 44 | + </Step> |
| 45 | + <Step title="Add a GitHub token"> |
| 46 | + Generate a [fine-grained personal access token](https://github.com/settings/personal-access-tokens) with read/write access to your repository. |
| 47 | + </Step> |
| 48 | + <Step title="Add to Repository Secrets"> |
| 49 | + Navigate to your repository's `Settings > Secrets and variables > Actions`. Select **New repository secret**, name it `OPENAPI_SYNC_TOKEN`, add your token, and click **Add secret**. |
| 50 | + </Step> |
| 51 | +</Steps> |
| 52 | +By default, this will create daily PRs with API spec updates to the repo containing your Fern folder. If you would like to adjust the frequency, learn more about GitHub's [schedule event](https://docs.github.com/en/actions/reference/events-that-trigger-workflows#schedule). |
| 53 | + |
| 54 | +<Info> For detailed configuration options and other use cases, see the [sync-openapi GitHub Action README](https://github.com/fern-api/sync-openapi). </Info> |
0 commit comments