Skip to content

Commit 28a625f

Browse files
fix(docs): Update automation.mdx (#69)
1 parent 4fbcac5 commit 28a625f

File tree

2 files changed

+51
-9
lines changed

2 files changed

+51
-9
lines changed

fern/products/api-definition/api-definition.yml

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -60,7 +60,7 @@ navigation:
6060
- page: Overlay Customizations
6161
icon: fa-regular fa-shuffle
6262
path: ./pages/openapi/overrides.mdx
63-
- page: Automatic Updates
63+
- page: Sync your OpenAPI Specification
6464
icon: fa-regular fa-arrows-rotate
6565
path: ./pages/openapi/automation.mdx
6666
- section: Integrate your Server Framework
@@ -150,4 +150,4 @@ navigation:
150150
- page: Export to OpenAPI
151151
icon: fa-regular fa-file-export
152152
slug: export-openapi
153-
path: ./pages/fern-definition/export-openapi.mdx
153+
path: ./pages/fern-definition/export-openapi.mdx
Lines changed: 49 additions & 7 deletions
Original file line numberDiff line numberDiff line change
@@ -1,12 +1,54 @@
11
---
2-
title: Automatically Update
2+
title: Sync your OpenAPI Specification
33
subtitle: Pull your latest OpenAPI Specification into your Fern Folder automatically.
44
---
55

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
1243
```
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

Comments
 (0)