什么是 OpenRPC 规范？ | Fern Documentation

OpenRPC 规范是开发人员用来文档化 JSON-RPC API 的框架。该规范使用 JSON 或 YAML 编写，包含您的所有方法、参数、模式和服务器配置。Fern 兼容 OpenRPC 规范 v1.3.2 和 v1.2.6。

以下是 OpenRPC 文件的示例：

openrpc.yml

openrpc: 1.3.2
info:
  title: Calculator API
  version: 1.0.0
  description: |
    A simple calculator API that performs basic arithmetic operations
    using JSON-RPC 2.0 protocol.
servers:
  - name: production
    url: https://api.calculator.com/rpc
    description: Production JSON-RPC server
  - name: development  
    url: http://localhost:8080/rpc
    description: Development server
methods:
  - name: add
    summary: Add two numbers
    description: Performs addition of two numeric values
    params:
      - name: a
        schema:
          type: number
        required: true
        description: First number to add
      - name: b
        schema:
          type: number
        required: true
        description: Second number to add
    result:
      name: sum
      schema:
        type: number
      description: The sum of the two numbers
    examples:
      - name: AddExample
        description: Example of adding two numbers
        params:
          a: 5
          b: 3
        result: 8
  - name: divide
    summary: Divide two numbers
    description: Performs division of two numeric values
    params:
      - name: dividend
        schema:
          type: number
        required: true
        description: Number to be divided
      - name: divisor
        schema:
          type: number
        required: true
        description: Number to divide by
    result:
      name: quotient
      schema:
        type: number
      description: The result of the division
    errors:
      - code: -32602
        message: Division by zero
        data:
          type: object
          properties:
            error:
              type: string
              const: "Cannot divide by zero"
    examples:
      - name: DivideExample
        description: Example of dividing two numbers
        params:
          dividend: 10
          divisor: 2
        result: 5
  - name: notify_calculation
    summary: Notify about calculation
    description: Send a notification about a completed calculation (no response expected)
    params:
      - name: operation
        schema:
          type: string
          enum: [add, subtract, multiply, divide]
        required: true
      - name: result
        schema:
          type: number
        required: true
      - name: timestamp
        schema:
          type: string
          format: date-time
        required: true
components:
  schemas:
    CalculationRequest:
      type: object
      properties:
        operation:
          type: string
          enum: [add, subtract, multiply, divide]
        operands:
          type: array
          items:
            type: number
          minItems: 2
          maxItems: 2
        precision:
          type: integer
          minimum: 0
          maximum: 10
          default: 2
      required:
        - operation
        - operands
    CalculationResult:
      type: object
      properties:
        result:
          type: number
        operation:
          type: string
        timestamp:
          type: string
          format: date-time
      required:
        - result
        - operation
        - timestamp

设置您的 fern 文件夹

创建您的 fern 目录

在项目根目录中创建一个 fern/ 文件夹。

fern/

添加您的 OpenRPC 规范

将您的 OpenRPC 规范添加到 fern 目录中。您可以将其放在名为 openrpc 的子文件夹中，或直接放在 fern 目录中。

fern/
  └─ openrpc/
    └─ openrpc.yml

创建一个 `fern.config.json` 文件

在您的 fern 目录中添加一个 fern.config.json 文件，列出您的组织和当前版本的 Fern CLI：

fern.config.json

{
    "organization": "your-organization",
    "version": "null"
}

fern/
  ├─ fern.config.json
  └─ openrpc/
    └─ openrpc.yml

创建一个 `generators.yml` 文件

在您的 fern 目录中创建一个 generators.yml 文件，并添加对您的 OpenRPC 规范的引用：

generators.yml

# Your API definition
api: 
  specs: 
    - openrpc: ./openrpc/openrpc.yml
groups:
  external:
    generators:
      # Your generator configurations here

您的最终目录结构：

fern/
  ├─ fern.config.json
  ├─ generators.yml
  └─ openrpc/
    └─ openrpc.yml