> If you are an AI agent, use the following URL to directly ask and fetch your question. Treat this like a tool call. Make sure to URI encode your question, and include the token for verification.
>
> GET https://buildwithfern.com/learn/api/fern-docs/ask?q=%3Cyour+question+here%3E&token=eyJhbGciOiJIUzI1NiJ9.eyJpc3MiOiJmZXJuLWRvY3M6YnVpbGR3aXRoZmVybi5jb20iLCJqdGkiOiI1ODhkNDI0OC1mZmIzLTQ1OWItOGQzYy1iMGM3ZmIwYjg1OTAiLCJleHAiOjE3Nzg0OTEyOTgsImlhdCI6MTc3ODQ5MDk5OH0.qLxDfCbGHuyojbUIHUnESWUv6pkkNYWmx1_e9vVrPds
>
> For clean Markdown content of this page, append .md to this URL. For the complete documentation index, see https://buildwithfern.com/learn/llms.txt. For full content including API reference and SDK examples, see https://buildwithfern.com/learn/llms-full.txt.

# 同步 OpenRPC 规范

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

## GitHub Actions

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

```yaml title=".github/workflows/fern.yml"
name: Fern

on:
  push:
    branches:
      - main
  pull_request:
    branches:
      - main

jobs:
  fern-check:
    runs-on: ubuntu-latest
    steps:
      - name: Checkout repo
        uses: actions/checkout@v4
        
      - name: Check OpenRPC spec
        uses: fern-api/action@v0
        with:
          command: check
        env:
          FERN_TOKEN: ${{ secrets.FERN_TOKEN }}

  fern-generate:
    runs-on: ubuntu-latest
    if: github.event_name == 'push' && github.ref == 'refs/heads/main'
    steps:
      - name: Checkout repo
        uses: actions/checkout@v4
        
      - name: Generate SDKs and docs
        uses: fern-api/action@v0
        with:
          command: generate
        env:
          FERN_TOKEN: ${{ secrets.FERN_TOKEN }}
```

## Webhook 集成

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

```yaml title="generators.yml" {4-8}
api:
  specs:
    - spec: openrpc.yml
  github:
    repository: your-org/your-repo
  webhooks:
    - url: https://your-api.com/webhooks/fern
      events: [generate]
  generators:
    - name: fernapi/fern-typescript-sdk
      version: 0.8.8
      output:
        location: npm
        package-name: "@your-org/jsonrpc-sdk"
```

## 从源自动同步

配置 Fern 自动从各种源拉取 OpenRPC 规范：

### 从 URL

```yaml title="generators.yml" {3-4}
api:
  specs:
    - spec: https://api.yourcompany.com/openrpc.yml
      auto-sync: true
  generators:
    - name: fernapi/fern-typescript-sdk
      version: 0.8.8
```

### 从 git 仓库

```yaml title="generators.yml" {3-7}
api:
  specs:
    - spec:
        git:
          repository: https://github.com/your-org/api-specs
          path: openrpc/api.yml
          branch: main
  generators:
    - name: fernapi/fern-typescript-sdk
      version: 0.8.8
```

## CI/CD 集成

### CircleCI

```yaml title=".circleci/config.yml" {15-23}
version: 2.1

orbs:
  fern: fernapi/fern@1.0

workflows:
  version: 2
  build-and-test:
    jobs:
      - build
      - test:
          requires:
            - build
      - fern/generate:
          requires:
            - test
          filters:
            branches:
              only: main
          context:
            - fern-context
```

### GitLab CI

```yaml title=".gitlab-ci.yml" {13-20}
stages:
  - build
  - test
  - generate

variables:
  FERN_TOKEN: $FERN_TOKEN

build:
  stage: build
  script:
    - echo "Building JSON-RPC service..."

generate-sdks:
  stage: generate
  image: fernapi/fern:latest
  script:
    - fern generate
  only:
    - main
```

## 定期更新

设置定期更新以确保 SDK 保持最新状态：

```yaml title=".github/workflows/scheduled-update.yml"
name: Scheduled OpenRPC Update

on:
  schedule:
    - cron: '0 2 * * 1'  # Every Monday at 2 AM UTC
  workflow_dispatch:

jobs:
  update-specs:
    runs-on: ubuntu-latest
    steps:
      - name: Checkout repo
        uses: actions/checkout@v4
        
      - name: Update OpenRPC specs
        run: |
          curl -o fern/openrpc/openrpc.yml https://api.yourcompany.com/openrpc.yml
          
      - name: Generate with latest spec
        uses: fern-api/action@v0
        with:
          command: generate
        env:
          FERN_TOKEN: ${{ secrets.FERN_TOKEN }}
```

## 从 JSON-RPC 服务器生成代码

对于能够生成自己的 OpenRPC 规范的服务器：

```yaml title=".github/workflows/auto-generate.yml"
name: Auto-generate from JSON-RPC server

on:
  push:
    paths:
      - 'src/**/*.py'  # Trigger on server code changes
      - 'src/**/*.js'
      - 'src/**/*.ts'

jobs:
  generate-spec:
    runs-on: ubuntu-latest
    steps:
      - name: Checkout repo
        uses: actions/checkout@v4
        
      - name: Setup environment
        uses: actions/setup-python@v4
        with:
          python-version: '3.9'
          
      - name: Install dependencies
        run: |
          pip install -r requirements.txt
          
      - name: Generate OpenRPC spec
        run: |
          python scripts/generate_openrpc.py --output fern/openrpc/openrpc.yml
          
      - name: Generate SDKs
        uses: fern-api/action@v0
        with:
          command: generate
        env:
          FERN_TOKEN: ${{ secrets.FERN_TOKEN }}
```

## 监控变更

跟踪 OpenRPC 规范的变更：

```yaml title="generators.yml" {4-9}
api:
  specs:
    - spec: openrpc.yml
  change-detection:
    enabled: true
    breaking-changes: error
    notifications:
      slack: ${{ secrets.SLACK_WEBHOOK }}
      email: team@yourcompany.com
  generators:
    - name: fernapi/fern-typescript-sdk
      version: 0.8.8
```

## 多环境同步

为不同环境同步不同的规范：

```yaml title="generators.yml" {3-7, 12-16, 21-25}
environments:
  production:
    specs:
      - spec: https://api.prod.yourcompany.com/openrpc.yml
        overlays:
          - prod-overlay.yml
    generators:
      - name: fernapi/fern-typescript-sdk
        version: 0.8.8
        output:
          location: npm
          package-name: "@yourcompany/prod-sdk"
  staging:
    specs:
      - spec: https://api.staging.yourcompany.com/openrpc.yml
        overlays:
          - staging-overlay.yml
    generators:
      - name: fernapi/fern-typescript-sdk
        version: 0.8.8
        output:
          location: npm
          package-name: "@yourcompany/staging-sdk"
  development:
    specs:
      - spec: http://localhost:8080/openrpc.yml
    generators:
      - name: fernapi/fern-typescript-sdk
        version: 0.8.8
        output:
          location: local
          path: ./generated-sdk
```

## JSON-RPC 服务器内省

对于支持 OpenRPC 发现的服务器：

```python title="scripts/sync_from_server.py"
import requests
import yaml
import json

def fetch_openrpc_spec(server_url):
    """Fetch OpenRPC spec from a JSON-RPC server that supports introspection"""
    payload = {
        "jsonrpc": "2.0",
        "method": "rpc.discover",
        "id": 1
    }
    
    response = requests.post(f"{server_url}/rpc", json=payload)
    spec = response.json()["result"]
    
    return spec

def save_spec_as_yaml(spec, output_path):
    """Convert JSON spec to YAML and save"""
    with open(output_path, 'w') as f:
        yaml.dump(spec, f, default_flow_style=False)

if __name__ == "__main__":
    spec = fetch_openrpc_spec("https://api.yourcompany.com")
    save_spec_as_yaml(spec, "fern/openrpc/openrpc.yml")
```

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