OpenAPI 规范

OpenAPI 3.1接口设计片段，供评审资源与响应格式；当前没有随本站部署的API服务，此片段不是可直接调用的接口。

规范文件随版本发布，任何破坏性变更都会升主版本。

示例片段给出 /v1/metrics/{id} 的定义，包含错误响应与 ETag。此片段不是完整OpenAPI文档，生产接入需补齐认证、参数、响应必填字段与服务地址。

openapi: 3.1.0
info:
  title: SIYB E Public API
  version: 1.0.0
  description: 环境感知技术平台结构化对象接口
servers:
  - url: https://api.siybe.com/v1
paths:
  /metrics/{metric_id}:
    get:
      summary: 获取指标定义
      parameters:
        - name: metric_id
          in: path
          required: true
          schema: { type: string }
          example: snow-water-equivalent
      responses:
        '200':
          description: OK
          headers:
            ETag: { schema: { type: string } }
          content:
            application/json:
              schema:
                type: object
                properties:
                  metric_id:   { type: string }
                  display_name:{ type: object, properties: { zh: {type: string}, en: {type: string} } }
                  symbol:      { type: string }
                  default_unit:{ type: string }
                  domain:      { type: string }
        '404':
          description: Metric not found