openapi: 3.0.0
info:
  title: 智能API测试助手 - 服务接口
  description: |
    本项目自身暴露给前端（frontend/index.html）的后端服务接口。
    前端通过这些接口，把"OpenAPI 文档 + 目标 API 地址"发给后端，
    后端跑完 5 个 Agent 的流水线后，把测试结果返回给前端。

    这正好演示了本工具的核心用途：拿一份 OpenAPI 文档去测接口——
    现在这份文档描述的是"测试助手自己"的接口，实现"自己测自己"。
  version: 1.0.0
servers:
  - url: http://localhost:8000
    description: 本地开发服务器（运行 python server.py 后启动）
paths:
  /:
    get:
      summary: 获取前端页面
      description: 返回测试助手的前端可视化页面（frontend/index.html）
      responses:
        '200':
          description: 成功返回前端 HTML 页面
          content:
            text/html:
              schema:
                type: string
  /api/test:
    post:
      summary: 执行智能 API 测试
      description: |
        核心接口。传入一份 OpenAPI 文档和目标 API 的基础地址，
        后端自动完成「解析文档 → 生成用例 → 执行测试 → 验证结果 → 统计汇总」全流程。
      requestBody:
        required: true
        description: |
          请求体必须包含 base_url，以及 openapi_text 和 openapi_url 中的一个：
          - 两个来源字段同时提供或都没提供 → 返回 400
          - 缺少必填字段（如 base_url）或字段类型错误 → 返回 422
          headers 可选，用于给被测接口透传认证等请求头。
        content:
          application/json:
            schema:
              type: object
              required:
                - base_url
              oneOf:
                - required:
                    - openapi_text
                  not:
                    required:
                      - openapi_url
                - required:
                    - openapi_url
                  not:
                    required:
                      - openapi_text
              properties:
                openapi_text:
                  type: string
                  description: OpenAPI 文档内容（支持 yaml 或 json 文本）
                openapi_url:
                  type: string
                  format: uri
                  description: OpenAPI 文档 URL，由后端直接抓取
                base_url:
                  type: string
                  description: 目标 API 的基础地址，如 https://jsonplaceholder.typicode.com
                headers:
                  type: object
                  description: '全局请求头(可选)，如 {"Authorization": "Bearer xxx"}，会原样透传给被测接口的每个请求'
                  additionalProperties:
                    type: string
            example:
              openapi_text: |
                openapi: 3.0.0
                info:
                  title: 示例
                  version: 1.0.0
                paths:
                  /users:
                    get:
                      summary: 获取用户列表
                      responses:
                        '200':
                          description: 成功
              base_url: https://jsonplaceholder.typicode.com
      responses:
        '200':
          description: 测试完成，返回汇总统计和每个用例的验证结果
          content:
            application/json:
              schema:
                type: object
                required:
                  - summary
                  - results
                properties:
                  summary:
                    type: object
                    description: 汇总统计
                    properties:
                      total:
                        type: integer
                        description: 用例总数
                      passed:
                        type: integer
                        description: 通过数
                      failed:
                        type: integer
                        description: 失败数
                      pass_rate:
                        type: number
                        description: 通过率（百分比，保留 1 位小数）
                  results:
                    type: array
                    description: 每个用例的验证结果
                    items:
                      type: object
                      properties:
                        case:
                          type: object
                          description: 原始测试用例（含 name / case_type / path / method / expected_status 等）
                        result:
                          type: object
                          description: 实际执行结果（含 status_code / elapsed / body / error 等）
                        passed:
                          type: boolean
                          description: 该用例是否通过
                        errors:
                          type: array
                          description: 失败原因列表（通过时为空）
                          items:
                            type: string
        '422':
          description: 请求体验证失败：缺少必填字段（如 base_url）或字段类型错误（FastAPI/pydantic 校验）
        '400':
          description: openapi_text 与 openapi_url 必须二选一（同时提供或同时缺失），或文档解析不出任何接口
        '500':
          description: 测试执行失败（如 LLM 调用失败、被测目标网络异常），服务端返回友好错误提示