> ## Documentation Index
> Fetch the complete documentation index at: https://learn.orbexa.io/llms.txt
> Use this file to discover all available pages before exploring further.

# OTR OpenAPI 3.0规范与SDK生成

> OTR信任查询API的OpenAPI 3.0完整规范文档，包含/api/otr/verify端点请求参数与响应体YAML定义、TrustResponse等JSON Schema数据模型与六维度评分结构体，以及通过openapi-generator自动生成TypeScript与Python等多语言客户端SDK的操作步骤

# OpenAPI 规范

## 8.1 OpenAPI 3.0概述

OTR的REST API遵循 [OpenAPI 3.0](https://swagger.io/specification/) 规范。OpenAPI规范是一个标准的API描述格式，可以用于：

* 自动生成客户端SDK（TypeScript、Python、Go等）
* 生成交互式API文档
* 自动化API测试
* 导入Postman等工具

## 8.2 OTR API规范摘要

```yaml theme={null}
openapi: 3.0.3
info:
  title: OTR Trust Verification API
  description: 查询域名的OTR信任评分和信号明细
  version: 1.0.0
  contact:
    name: ORBEXA
    url: https://orbexa.io

servers:
  - url: https://orbexa.io
    description: 生产环境

paths:
  /api/otr/verify/{domain}:
    get:
      summary: 查询域名信任评分
      description: 返回指定域名的六维度信任评分、信号明细和实体数据
      parameters:
        - name: domain
          in: path
          required: true
          schema:
            type: string
          description: 要查询的域名（不含协议前缀）
          example: example.com
      responses:
        '200':
          description: 成功返回信任评分数据
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TrustReport'
        '404':
          description: 域名未找到
        '429':
          description: 请求频率超限

  /.well-known/otr/verify/{domain}:
    get:
      summary: .well-known端点（与主API相同）
      description: 符合RFC 8615的服务发现端点，返回与主API相同的数据
      parameters:
        - name: domain
          in: path
          required: true
          schema:
            type: string
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TrustReport'

components:
  schemas:
    TrustReport:
      type: object
      properties:
        domain:
          type: string
          description: 查询的域名
        name:
          type: string
          description: 商家名称
        trust_score:
          type: number
          minimum: 0
          maximum: 100
          description: 综合信任评分
        badge:
          type: string
          enum: [PLATINUM, GOLD, SILVER, BRONZE, UNRATED]
          description: 信任徽章
        dimensions:
          $ref: '#/components/schemas/Dimensions'
        entity_data:
          type: object
          description: 第三方验证的实体信息
        agent_commerce:
          $ref: '#/components/schemas/AgentCommerce'
        scanned_at:
          type: string
          format: date-time
        otr_id:
          type: string

    Dimensions:
      type: object
      properties:
        V:
          $ref: '#/components/schemas/DimensionScore'
        S:
          $ref: '#/components/schemas/DimensionScore'
        G:
          $ref: '#/components/schemas/DimensionScore'
        T:
          $ref: '#/components/schemas/DimensionScore'
        D:
          $ref: '#/components/schemas/DimensionScore'
        F:
          $ref: '#/components/schemas/DimensionScore'

    DimensionScore:
      type: object
      properties:
        score:
          type: number
          nullable: true
        signals:
          type: array
          items:
            $ref: '#/components/schemas/Signal'

    Signal:
      type: object
      properties:
        signal_name:
          type: string
        status:
          type: string
          enum: [detected, not_found, not_scanned, fetch_failed]
        value:
          description: 信号具体值
        evidence:
          type: string
        source_url:
          type: string

    AgentCommerce:
      type: object
      properties:
        llms_txt:
          type: boolean
        agent_json:
          type: boolean
        schema_org_product:
          type: boolean
        sitemap:
          type: boolean
```

## 8.3 用OpenAPI生成SDK

### TypeScript

```bash theme={null}
npx openapi-typescript-codegen --input otr-api.yaml --output ./src/otr-client
```

### Python

```bash theme={null}
pip install openapi-python-client
openapi-python-client generate --path otr-api.yaml
```

## 8.4 导入Postman

1. 打开Postman → Import → 选择OpenAPI文件
2. Postman自动创建请求集合
3. 直接测试每个端点

***

**下一章**: [AI代理如何调用OTR](/zh/book-2/ch9-agent-integration) — AI代理的信任查询集成模式