webstatus/status/templates/status/api_docs.html

{% extends 'status/base.html' %}

{% block title %}API说明{% endblock %}

{% block content %}
<div class="bg-white rounded-xl p-6 card-shadow mb-6">
    <h1 class="text-2xl font-bold text-gray-800 mb-4">API接口说明</h1>
    <p class="text-gray-600 mb-6">本系统提供以下RESTful API接口，用于服务状态的上报和查询。</p>
    
    <div class="mb-8">
        <h2 class="text-xl font-bold text-gray-800 mb-4">认证方式</h2>
        <div class="bg-blue-50 border-l-4 border-blue-500 p-4 mb-4">
            <p class="text-blue-700">目前所有API接口均无需认证，可直接访问。后续版本可能会添加认证机制。</p>
        </div>
    </div>
    
    <div class="mb-8">
        <h2 class="text-xl font-bold text-gray-800 mb-4">API端点列表</h2>
        
        <div class="mb-6">
            <h3 class="text-lg font-semibold text-gray-800 mb-2">POST /api/checkin/ - 客户端上报接口</h3>
            <p class="text-gray-600 mb-3">用于客户端上报服务状态信息。如果服务不存在，系统会自动创建。</p>
            
            <div class="mb-4">
                <h4 class="font-medium text-gray-700 mb-2">请求体示例：</h4>
                <pre class="bg-gray-800 text-gray-100 p-4 rounded-lg overflow-x-auto"><code>{
  "service_name": "Web服务",
  "host": "192.168.1.100",
  "port": 80,
  "check_type": "http",
  "status": "UP",
  "response_time": 120.5,
  "message": "连接成功"
}</code></pre>
            </div>
            
            <div>
                <h4 class="font-medium text-gray-700 mb-2">响应示例：</h4>
                <pre class="bg-gray-800 text-gray-100 p-4 rounded-lg overflow-x-auto"><code>{
  "code": 200,
  "message": "服务状态已更新",
  "service_id": 1
}</code></pre>
            </div>
        </div>
        
        <div class="mb-6">
            <h3 class="text-lg font-semibold text-gray-800 mb-2">GET /api/services/ - 服务列表查询接口</h3>
            <p class="text-gray-600 mb-3">获取所有服务的列表及其最新状态。</p>
            
            <div>
                <h4 class="font-medium text-gray-700 mb-2">响应示例：</h4>
                <pre class="bg-gray-800 text-gray-100 p-4 rounded-lg overflow-x-auto"><code>[
  {
    "id": 1,
    "name": "Web服务",
    "host": "192.168.1.100",
    "port": 80,
    "check_type": "http",
    "group": "Web服务组",
    "description": "公司主网站",
    "latest_status": "UP",
    "latest_check_time": "2025-06-15T10:30:00Z",
    "latest_response_time": 120.5
  }
]</code></pre>
            </div>
        </div>
        
        <div class="mb-6">
            <h3 class="text-lg font-semibold text-gray-800 mb-2">GET /api/services/{id}/history/ - 服务历史记录查询接口</h3>
            <p class="text-gray-600 mb-3">获取指定服务的历史检测记录。</p>
            
            <div>
                <h4 class="font-medium text-gray-700 mb-2">响应示例：</h4>
                <pre class="bg-gray-800 text-gray-100 p-4 rounded-lg overflow-x-auto"><code>{
  "count": 1,
  "total_pages": 1,
  "current_page": 1,
  "page_size": 20,
  "results": [
    {
      "id": 1,
      "service": 1,
      "status": "UP",
      "response_time": 120.5,
      "message": "连接成功",
      "check_time": "2025-06-15T10:30:00Z"
    }
  ]
}</code></pre>
            </div>
        </div>
        
        <div class="mb-6">
            <h3 class="text-lg font-semibold text-gray-800 mb-2">GET /api/status-summary/ - 状态摘要查询接口</h3>
            <p class="text-gray-600 mb-3">获取所有服务的状态摘要统计信息。</p>
            
            <div>
                <h4 class="font-medium text-gray-700 mb-2">响应示例：</h4>
                <pre class="bg-gray-800 text-gray-100 p-4 rounded-lg overflow-x-auto"><code>{
  "total_services": 10,
  "up_count": 8,
  "down_count": 1,
  "unknown_count": 1
}</code></pre>
            </div>
        </div>
    </div>
    
    <div class="mb-6">
        <h2 class="text-xl font-bold text-gray-800 mb-4">状态码说明</h2>
        <ul class="list-disc pl-5 text-gray-600 space-y-1">
            <li><strong>UP</strong>: 服务正常运行</li>
            <li><strong>DOWN</strong>: 服务不可用</li>
            <li><strong>UNKNOWN</strong>: 服务状态未知</li>
        </ul>
    </div>
    
    <div class="mb-6">
        <h2 class="text-xl font-bold text-gray-800 mb-4">检测类型说明</h2>
        <ul class="list-disc pl-5 text-gray-600 space-y-1">
            <li><strong>http</strong>: HTTP检测</li>
            <li><strong>https</strong>: HTTPS检测</li>
            <li><strong>tcp</strong>: TCP端口检测</li>
            <li><strong>ping</strong>: PING检测</li>
        </ul>
    </div>
</div>
{% endblock %}