Sync your OpenRPC specification

Automate OpenRPC spec syncing to keep SDKs and documentation current. Set up GitHub Actions, webhooks, and CI/CD integrations with Fern.

Sync your OpenRPC specification

Automate OpenRPC spec syncing to keep SDKs and documentation current. Set up GitHub Actions, webhooks, and CI/CD integrations with Fern.

Keeping your OpenRPC specifications in sync with your codebase is crucial for maintaining accurate SDKs and documentation. Fern provides several automation options to streamline this process.

GitHub Actions

Use Fern’s GitHub Action to automatically update SDKs and docs when your OpenRPC spec changes:

.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 OpenRPC 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 integration

Set up webhooks to trigger SDK generation when your OpenRPC spec is updated:

generators.yml

1 api:
2   specs:
3     - spec: openrpc.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/jsonrpc-sdk"

Auto-sync from source

Configure Fern to automatically pull your OpenRPC specification from various sources:

From URL

generators.yml

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

From git repository

generators.yml

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

CI/CD integration

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 JSON-RPC service..."
13 
14 generate-sdks:
15   stage: generate
16   image: fernapi/fern:latest
17   script:
18     - fern generate
19   only:
20     - main

Scheduled updates

Set up scheduled updates to ensure your SDKs stay current:

.github/workflows/scheduled-update.yml

1 name: Scheduled OpenRPC 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 OpenRPC specs
16         run: |
17           curl -o fern/openrpc/openrpc.yml https://api.yourcompany.com/openrpc.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 }}

Code generation from JSON-RPC server

For servers that can generate their own OpenRPC specifications:

.github/workflows/auto-generate.yml

1 name: Auto-generate from JSON-RPC server
2 
3 on:
4   push:
5     paths:
6       - 'src/**/*.py'  # Trigger on server code changes
7       - 'src/**/*.js'
8       - 'src/**/*.ts'
9 
10 jobs:
11   generate-spec:
12     runs-on: ubuntu-latest
13     steps:
14       - name: Checkout repo
15         uses: actions/checkout@v4
16         
17       - name: Setup environment
18         uses: actions/setup-python@v4
19         with:
20           python-version: '3.9'
21           
22       - name: Install dependencies
23         run: |
24           pip install -r requirements.txt
25           
26       - name: Generate OpenRPC spec
27         run: |
28           python scripts/generate_openrpc.py --output fern/openrpc/openrpc.yml
29           
30       - name: Generate SDKs
31         uses: fern-api/action@v0
32         with:
33           command: generate
34         env:
35           FERN_TOKEN: ${{ secrets.FERN_TOKEN }}

Monitoring changes

Track changes to your OpenRPC specification:

generators.yml

1 api:
2   specs:
3     - spec: openrpc.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

Multi-environment sync

Sync different specifications for different environments:

generators.yml

1 environments:
2   production:
3     specs:
4       - spec: https://api.prod.yourcompany.com/openrpc.yml
5         overlays:
6           - prod-overlay.yml
7     generators:
8       - name: fernapi/fern-typescript-sdk
9         version: 0.8.8
10         output:
11           location: npm
12           package-name: "@yourcompany/prod-sdk"
13   staging:
14     specs:
15       - spec: https://api.staging.yourcompany.com/openrpc.yml
16         overlays:
17           - staging-overlay.yml
18     generators:
19       - name: fernapi/fern-typescript-sdk
20         version: 0.8.8
21         output:
22           location: npm
23           package-name: "@yourcompany/staging-sdk"
24   development:
25     specs:
26       - spec: http://localhost:8080/openrpc.yml
27     generators:
28       - name: fernapi/fern-typescript-sdk
29         version: 0.8.8
30         output:
31           location: local
32           path: ./generated-sdk

JSON-RPC server introspection

For servers that support OpenRPC discovery:

scripts/sync_from_server.py

1 import requests
2 import yaml
3 import json
4 
5 def fetch_openrpc_spec(server_url):
6     """Fetch OpenRPC spec from a JSON-RPC server that supports introspection"""
7     payload = {
8         "jsonrpc": "2.0",
9         "method": "rpc.discover",
10         "id": 1
11     }
12     
13     response = requests.post(f"{server_url}/rpc", json=payload)
14     spec = response.json()["result"]
15     
16     return spec
17 
18 def save_spec_as_yaml(spec, output_path):
19     """Convert JSON spec to YAML and save"""
20     with open(output_path, 'w') as f:
21         yaml.dump(spec, f, default_flow_style=False)
22 
23 if __name__ == "__main__":
24     spec = fetch_openrpc_spec("https://api.yourcompany.com")
25     save_spec_as_yaml(spec, "fern/openrpc/openrpc.yml")

This ensures that any breaking changes to your OpenRPC specification are detected and the appropriate team members are notified before the changes are propagated to your SDKs and documentation.

Keeping your OpenRPC specifications in sync with your codebase is crucial for maintaining accurate SDKs and documentation. Fern provides several automation options to streamline this process.

GitHub Actions

Use Fern’s GitHub Action to automatically update SDKs and docs when your OpenRPC spec changes:

.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 OpenRPC 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 integration

Set up webhooks to trigger SDK generation when your OpenRPC spec is updated:

generators.yml

1 api:
2   specs:
3     - spec: openrpc.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/jsonrpc-sdk"

Auto-sync from source

Configure Fern to automatically pull your OpenRPC specification from various sources:

From URL

generators.yml

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

From git repository

generators.yml

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

CI/CD integration

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 JSON-RPC service..."
13 
14 generate-sdks:
15   stage: generate
16   image: fernapi/fern:latest
17   script:
18     - fern generate
19   only:
20     - main

Scheduled updates

Set up scheduled updates to ensure your SDKs stay current:

.github/workflows/scheduled-update.yml

1 name: Scheduled OpenRPC 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 OpenRPC specs
16         run: |
17           curl -o fern/openrpc/openrpc.yml https://api.yourcompany.com/openrpc.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 }}

Code generation from JSON-RPC server

For servers that can generate their own OpenRPC specifications:

.github/workflows/auto-generate.yml

1 name: Auto-generate from JSON-RPC server
2 
3 on:
4   push:
5     paths:
6       - 'src/**/*.py'  # Trigger on server code changes
7       - 'src/**/*.js'
8       - 'src/**/*.ts'
9 
10 jobs:
11   generate-spec:
12     runs-on: ubuntu-latest
13     steps:
14       - name: Checkout repo
15         uses: actions/checkout@v4
16         
17       - name: Setup environment
18         uses: actions/setup-python@v4
19         with:
20           python-version: '3.9'
21           
22       - name: Install dependencies
23         run: |
24           pip install -r requirements.txt
25           
26       - name: Generate OpenRPC spec
27         run: |
28           python scripts/generate_openrpc.py --output fern/openrpc/openrpc.yml
29           
30       - name: Generate SDKs
31         uses: fern-api/action@v0
32         with:
33           command: generate
34         env:
35           FERN_TOKEN: ${{ secrets.FERN_TOKEN }}

Monitoring changes

Track changes to your OpenRPC specification:

generators.yml

1 api:
2   specs:
3     - spec: openrpc.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

Multi-environment sync

Sync different specifications for different environments:

generators.yml

1 environments:
2   production:
3     specs:
4       - spec: https://api.prod.yourcompany.com/openrpc.yml
5         overlays:
6           - prod-overlay.yml
7     generators:
8       - name: fernapi/fern-typescript-sdk
9         version: 0.8.8
10         output:
11           location: npm
12           package-name: "@yourcompany/prod-sdk"
13   staging:
14     specs:
15       - spec: https://api.staging.yourcompany.com/openrpc.yml
16         overlays:
17           - staging-overlay.yml
18     generators:
19       - name: fernapi/fern-typescript-sdk
20         version: 0.8.8
21         output:
22           location: npm
23           package-name: "@yourcompany/staging-sdk"
24   development:
25     specs:
26       - spec: http://localhost:8080/openrpc.yml
27     generators:
28       - name: fernapi/fern-typescript-sdk
29         version: 0.8.8
30         output:
31           location: local
32           path: ./generated-sdk

JSON-RPC server introspection

For servers that support OpenRPC discovery:

scripts/sync_from_server.py

1 import requests
2 import yaml
3 import json
4 
5 def fetch_openrpc_spec(server_url):
6     """Fetch OpenRPC spec from a JSON-RPC server that supports introspection"""
7     payload = {
8         "jsonrpc": "2.0",
9         "method": "rpc.discover",
10         "id": 1
11     }
12     
13     response = requests.post(f"{server_url}/rpc", json=payload)
14     spec = response.json()["result"]
15     
16     return spec
17 
18 def save_spec_as_yaml(spec, output_path):
19     """Convert JSON spec to YAML and save"""
20     with open(output_path, 'w') as f:
21         yaml.dump(spec, f, default_flow_style=False)
22 
23 if __name__ == "__main__":
24     spec = fetch_openrpc_spec("https://api.yourcompany.com")
25     save_spec_as_yaml(spec, "fern/openrpc/openrpc.yml")

This ensures that any breaking changes to your OpenRPC specification are detected and the appropriate team members are notified before the changes are propagated to your SDKs and documentation.

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 OpenRPC 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 }}

1	api:
2	specs:
3	- spec: openrpc.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/jsonrpc-sdk"

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

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

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

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 JSON-RPC service..."
13
14	generate-sdks:
15	stage: generate
16	image: fernapi/fern:latest
17	script:
18	- fern generate
19	only:
20	- main

1	name: Scheduled OpenRPC 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 OpenRPC specs
16	run: \|
17	curl -o fern/openrpc/openrpc.yml https://api.yourcompany.com/openrpc.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 }}

1	name: Auto-generate from JSON-RPC server
2
3	on:
4	push:
5	paths:
6	- 'src/*/.py' # Trigger on server code changes
7	- 'src/*/.js'
8	- 'src/*/.ts'
9
10	jobs:
11	generate-spec:
12	runs-on: ubuntu-latest
13	steps:
14	- name: Checkout repo
15	uses: actions/checkout@v4
16
17	- name: Setup environment
18	uses: actions/setup-python@v4
19	with:
20	python-version: '3.9'
21
22	- name: Install dependencies
23	run: \|
24	pip install -r requirements.txt
25
26	- name: Generate OpenRPC spec
27	run: \|
28	python scripts/generate_openrpc.py --output fern/openrpc/openrpc.yml
29
30	- name: Generate SDKs
31	uses: fern-api/action@v0
32	with:
33	command: generate
34	env:
35	FERN_TOKEN: ${{ secrets.FERN_TOKEN }}

1	environments:
2	production:
3	specs:
4	- spec: https://api.prod.yourcompany.com/openrpc.yml
5	overlays:
6	- prod-overlay.yml
7	generators:
8	- name: fernapi/fern-typescript-sdk
9	version: 0.8.8
10	output:
11	location: npm
12	package-name: "@yourcompany/prod-sdk"
13	staging:
14	specs:
15	- spec: https://api.staging.yourcompany.com/openrpc.yml
16	overlays:
17	- staging-overlay.yml
18	generators:
19	- name: fernapi/fern-typescript-sdk
20	version: 0.8.8
21	output:
22	location: npm
23	package-name: "@yourcompany/staging-sdk"
24	development:
25	specs:
26	- spec: http://localhost:8080/openrpc.yml
27	generators:
28	- name: fernapi/fern-typescript-sdk
29	version: 0.8.8
30	output:
31	location: local
32	path: ./generated-sdk

1	import requests
2	import yaml
3	import json
4
5	def fetch_openrpc_spec(server_url):
6	"""Fetch OpenRPC spec from a JSON-RPC server that supports introspection"""
7	payload = {
8	"jsonrpc": "2.0",
9	"method": "rpc.discover",
10	"id": 1
11	}
12
13	response = requests.post(f"{server_url}/rpc", json=payload)
14	spec = response.json()["result"]
15
16	return spec
17
18	def save_spec_as_yaml(spec, output_path):
19	"""Convert JSON spec to YAML and save"""
20	with open(output_path, 'w') as f:
21	yaml.dump(spec, f, default_flow_style=False)
22
23	if __name__ == "__main__":
24	spec = fetch_openrpc_spec("https://api.yourcompany.com")
25	save_spec_as_yaml(spec, "fern/openrpc/openrpc.yml")