OpenAPI

Sync your OpenAPI Specification

Pull your latest OpenAPI Specification into your Fern Folder automatically.

Automatically pull your latest OpenAPI spec from a publicly available URL into your fern folder using the sync-openapi GitHub Action. This keeps your committed spec in sync with your live API without manual updates.

Setup

1

Configure the origin URL

Add the origin field to your generators.yml to specify where your OpenAPI spec is hosted:

generators.yml
1 api:
2   specs: 
3     - openapi: .path/to/openapi.json               # Definition file
4       overrides: .path/to-openapi-overrides.yml    # Overrides file
5       origin: https://api.example.com/openapi.json # URL to fetch latest spec from
2

Add the GitHub Action

Create .github/workflows/sync-openapi.yml in your repository:

1name: Sync OpenAPI Specs # can be customized
2on:                               # additional custom triggers can be configured
3  workflow_dispatch:              # Manual trigger
4  push:                                          
5    branches:
6      - main                      # Trigger on push to
7  schedule:
8    - cron: '0 3 * * *'           # Daily at 3:00 AM UTC
9jobs:
10update-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
3

Create a GitHub token

Generate a fine-grained personal access token with Contents and Pull requests read/write permissions for your repository.

4

Add to Repository Secrets

In your repository, go to Settings > Secrets and variables > Actions. Click New repository secret, name it OPENAPI_SYNC_TOKEN, paste your token, and click Add secret.

This creates daily pull requests with any API spec updates. To change the frequency, modify the cron schedule (see GitHub’s schedule syntax).

Other use cases

If your OpenAPI spec lives in a different repository (rather than at a public URL), you can sync it to your Fern folder using cross-repository sync. See the sync-openapi GitHub Action README for this and other advanced configurations.