// 定义API文档的JSON const swaggerDocument = { "openapi": "3.0.3", "info": { "title": "DNS Server API", "description": "DNS服务器完整API文档,包括统计信息、Shield管理、主机管理等功能。", "version": "1.1.0", "contact": { "name": "DNS Server 支持", "email": "support@dnsserver.com" }, "license": { "name": "Apache 2.0", "url": "http://www.apache.org/licenses/LICENSE-2.0.html" } }, "servers": [ { "url": "http://localhost:8080/api", "description": "本地开发服务器" }, { "url": "http://{host}:{port}/api", "description": "自定义服务器", "variables": { "host": { "default": "localhost" }, "port": { "default": "8080" } } } ], "paths": { "/stats": { "get": { "summary": "获取系统统计信息", "description": "获取DNS服务器和Shield的详细统计信息,包括查询量、CPU使用率等。", "tags": ["stats"], "responses": { "200": { "description": "成功获取统计信息", "content": { "application/json": { "schema": { "type": "object", "properties": { "dns": { "type": "object", "properties": { "Queries": {"type": "integer", "description": "总查询次数"}, "Blocked": {"type": "integer", "description": "被阻止的查询次数"}, "Allowed": {"type": "integer", "description": "允许的查询次数"}, "Errors": {"type": "integer", "description": "错误查询次数"}, "LastQuery": {"type": "string", "description": "最近一次查询时间"}, "AvgResponseTime": {"type": "number", "description": "平均响应时间(毫秒)"}, "TotalResponseTime": {"type": "number", "description": "总响应时间(毫秒)"}, "QueryTypes": {"type": "object", "description": "查询类型统计"}, "SourceIPs": {"type": "object", "description": "来源IP统计"}, "CpuUsage": {"type": "number", "description": "CPU使用率(百分比)"} } }, "shield": {"type": "object", "description": "Shield统计信息"}, "topQueryType": {"type": "string", "description": "最常见的查询类型"}, "activeIPs": {"type": "integer", "description": "活跃IP数量"}, "avgResponseTime": {"type": "number", "description": "平均响应时间(毫秒)"}, "cpuUsage": {"type": "number", "description": "CPU使用率(百分比)"}, "time": {"type": "string", "description": "统计时间"} } }, "examples": { "default": { "value": { "dns": { "Queries": 1250, "Blocked": 230, "Allowed": 1020, "Errors": 0, "LastQuery": "2023-07-15T14:30:45Z", "AvgResponseTime": 12.5, "TotalResponseTime": 15625, "QueryTypes": {"A": 850, "AAAA": 250, "CNAME": 150}, "SourceIPs": {"192.168.1.100": 500, "192.168.1.101": 750}, "CpuUsage": 0.15 }, "shield": {}, "topQueryType": "A", "activeIPs": 2, "avgResponseTime": 12.5, "cpuUsage": 0.15, "time": "2023-07-15T14:30:45Z" } } } } } }, "500": { "description": "服务器内部错误", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": {"type": "string", "description": "错误信息"} } }, "example": {"error": "无法获取统计信息"} } } } } } }, "/top-blocked": { "get": { "summary": "获取TOP被阻止域名", "description": "获取被阻止次数最多的域名列表。", "tags": ["stats"], "responses": { "200": { "description": "成功获取TOP被阻止域名", "content": { "application/json": { "schema": { "type": "array", "items": { "type": "object", "properties": { "domain": {"type": "string", "description": "域名"}, "count": {"type": "integer", "description": "被阻止次数"} } } }, "example": [ {"domain": "ad.example.com", "count": 150}, {"domain": "tracker.example.net", "count": 120} ] } } } } } }, "/top-resolved": { "get": { "summary": "获取TOP已解析域名", "description": "获取解析次数最多的域名列表。", "tags": ["stats"], "responses": { "200": { "description": "成功获取TOP已解析域名", "content": { "application/json": { "schema": { "type": "array", "items": { "type": "object", "properties": { "domain": {"type": "string", "description": "域名"}, "count": {"type": "integer", "description": "解析次数"} } } }, "example": [ {"domain": "google.com", "count": 200}, {"domain": "facebook.com", "count": 150} ] } } } } } }, "/top-clients": { "get": { "summary": "获取TOP客户端", "description": "获取查询量最多的客户端IP列表。", "tags": ["stats"], "responses": { "200": { "description": "成功获取TOP客户端", "content": { "application/json": { "schema": { "type": "array", "items": { "type": "object", "properties": { "ip": {"type": "string", "description": "客户端IP地址"}, "count": {"type": "integer", "description": "查询次数"} } } }, "example": [ {"ip": "192.168.1.100", "count": 500}, {"ip": "192.168.1.101", "count": 750} ] } } } } } }, "/top-domains": { "get": { "summary": "获取TOP域名", "description": "获取查询量最多的域名列表(包括被阻止和已解析的域名)。", "tags": ["stats"], "responses": { "200": { "description": "成功获取TOP域名", "content": { "application/json": { "schema": { "type": "array", "items": { "type": "object", "properties": { "domain": {"type": "string", "description": "域名"}, "count": {"type": "integer", "description": "查询次数"} } } }, "example": [ {"domain": "example.com", "count": 150}, {"domain": "google.com", "count": 120} ] } } } } } }, "/recent-blocked": { "get": { "summary": "获取最近被阻止的域名", "description": "获取最近被Shield阻止的域名列表。", "tags": ["stats"], "responses": { "200": { "description": "成功获取最近被阻止的域名", "content": { "application/json": { "schema": { "type": "array", "items": { "type": "object", "properties": { "domain": {"type": "string", "description": "域名"}, "timestamp": {"type": "string", "description": "阻止时间"} } } }, "example": [ {"domain": "ad.example.com", "timestamp": "2023-07-15T14:30:45Z"}, {"domain": "tracker.example.net", "timestamp": "2023-07-15T14:29:30Z"} ] } } } } } }, "/hourly-stats": { "get": { "summary": "获取小时统计", "description": "获取按小时统计的DNS查询数据。", "tags": ["stats"], "responses": { "200": { "description": "成功获取小时统计", "content": { "application/json": { "schema": { "type": "array", "items": { "type": "object", "properties": { "hour": {"type": "string", "description": "小时"}, "queries": {"type": "integer", "description": "查询次数"}, "blocked": {"type": "integer", "description": "被阻止次数"} } } }, "example": [ {"hour": "00", "queries": 120, "blocked": 20}, {"hour": "01", "queries": 90, "blocked": 15} ] } } } } } }, "/daily-stats": { "get": { "summary": "获取每日统计", "description": "获取最近7天的DNS查询统计数据。", "tags": ["stats"], "responses": { "200": { "description": "成功获取每日统计", "content": { "application/json": { "schema": { "type": "array", "items": { "type": "object", "properties": { "date": {"type": "string", "description": "日期"}, "queries": {"type": "integer", "description": "查询次数"}, "blocked": {"type": "integer", "description": "被阻止次数"} } } }, "example": [ {"date": "2023-07-09", "queries": 2500, "blocked": 450}, {"date": "2023-07-10", "queries": 2700, "blocked": 480} ] } } } } } }, "/monthly-stats": { "get": { "summary": "获取每月统计", "description": "获取最近30天的DNS查询统计数据。", "tags": ["stats"], "responses": { "200": { "description": "成功获取每月统计", "content": { "application/json": { "schema": { "type": "array", "items": { "type": "object", "properties": { "date": {"type": "string", "description": "日期"}, "queries": {"type": "integer", "description": "查询次数"}, "blocked": {"type": "integer", "description": "被阻止次数"} } } }, "example": [ {"date": "2023-06-15", "queries": 2500, "blocked": 450}, {"date": "2023-06-16", "queries": 2700, "blocked": 480} ] } } } } } }, "/query/type": { "get": { "summary": "获取查询类型统计", "description": "获取DNS查询类型的详细统计信息。", "tags": ["stats"], "responses": { "200": { "description": "成功获取查询类型统计", "content": { "application/json": { "schema": { "type": "array", "items": { "type": "object", "properties": { "type": {"type": "string", "description": "查询类型"}, "count": {"type": "integer", "description": "查询次数"} } } }, "example": [ {"type": "A", "count": 850}, {"type": "AAAA", "count": 250}, {"type": "CNAME", "count": 150} ] } } } } } }, "/shield": { "get": { "summary": "获取Shield配置", "description": "获取Shield的完整配置信息,包括启用状态、规则等。", "tags": ["shield"], "responses": { "200": { "description": "成功获取配置信息", "content": { "application/json": { "schema": { "type": "object", "properties": { "enabled": {"type": "boolean", "description": "是否启用Shield"}, "rulesCount": {"type": "integer", "description": "规则数量"}, "lastUpdate": {"type": "string", "description": "最后更新时间"}, "blacklists": {"type": "array", "description": "黑名单列表", "items": {"type": "object"}} } }, "example": { "enabled": true, "rulesCount": 5000, "lastUpdate": "2023-07-15T10:00:00Z", "blacklists": [] } } } }, "500": { "description": "服务器内部错误", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": {"type": "string", "description": "错误信息"} } }, "example": {"error": "无法获取Shield配置"} } } } } }, "post": { "summary": "更新Shield配置", "description": "更新Shield的全局配置信息。", "tags": ["shield"], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "enabled": {"type": "boolean", "description": "是否启用Shield"}, "updateInterval": {"type": "integer", "description": "更新间隔(秒)"} } }, "example": { "enabled": true, "updateInterval": 3600 } } } }, "responses": { "200": { "description": "成功更新配置", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": {"type": "string", "description": "操作状态"} } }, "example": {"status": "success"} } } }, "400": { "description": "请求参数错误", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": {"type": "string", "description": "错误信息"} } }, "example": {"error": "参数格式错误"} } } }, "500": { "description": "服务器内部错误", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": {"type": "string", "description": "错误信息"} } }, "example": {"error": "更新配置失败"} } } } } }, "put": { "summary": "重启Shield", "description": "重新加载和应用Shield规则。", "tags": ["shield"], "responses": { "200": { "description": "成功重启Shield", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": {"type": "string", "description": "操作状态"} } }, "example": {"status": "success"} } } }, "500": { "description": "服务器内部错误", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": {"type": "string", "description": "错误信息"} } }, "example": {"error": "重启失败"} } } } } } }, "/shield/blacklists": { "get": { "summary": "获取黑名单列表", "description": "获取所有远程黑名单的列表及详细信息。", "tags": ["shield"], "responses": { "200": { "description": "成功获取黑名单列表", "content": { "application/json": { "schema": { "type": "array", "items": { "type": "object", "properties": { "name": {"type": "string", "description": "黑名单名称"}, "url": {"type": "string", "description": "黑名单URL"}, "enabled": {"type": "boolean", "description": "是否启用"}, "lastUpdate": {"type": "string", "description": "最后更新时间"}, "status": {"type": "string", "description": "状态"}, "rulesCount": {"type": "integer", "description": "规则数量"} } } }, "example": [ { "name": "AdBlock List", "url": "https://example.com/ads.txt", "enabled": true, "lastUpdate": "2023-07-15T10:00:00Z", "status": "active", "rulesCount": 1500 } ] } } }, "500": { "description": "服务器内部错误", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": {"type": "string", "description": "错误信息"} } }, "example": {"error": "获取黑名单列表失败"} } } } } }, "post": { "summary": "添加黑名单", "description": "添加新的远程黑名单URL。", "tags": ["shield"], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": ["name", "url"], "properties": { "name": {"type": "string", "description": "黑名单名称"}, "url": {"type": "string", "description": "黑名单URL"}, "enabled": {"type": "boolean", "description": "是否启用", "default": true} } }, "example": { "name": "AdBlock List", "url": "https://example.com/ads.txt", "enabled": true } } } }, "responses": { "200": { "description": "成功添加黑名单", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": {"type": "string", "description": "操作状态"} } }, "example": {"status": "success"} } } }, "400": { "description": "请求参数错误", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": {"type": "string", "description": "错误信息"} } }, "example": {"error": "名称和URL为必填项"} } } }, "500": { "description": "服务器内部错误", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": {"type": "string", "description": "错误信息"} } }, "example": {"error": "添加黑名单失败"} } } } } }, "put": { "summary": "更新黑名单列表(包括启用/禁用状态)", "description": "更新黑名单列表(包括启用/禁用状态)。", "tags": ["shield"], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "blacklists": { "type": "array", "items": { "type": "object", "properties": { "name": {"type": "string", "description": "黑名单名称"}, "url": {"type": "string", "description": "黑名单URL"}, "enabled": {"type": "boolean", "description": "是否启用"} } } } } }, "example": { "blacklists": [ { "name": "AdBlock List", "url": "https://example.com/ads.txt", "enabled": true } ] } } } }, "responses": { "200": { "description": "成功更新黑名单列表", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": {"type": "string", "description": "操作状态"} } }, "example": {"status": "success"} } } }, "400": { "description": "请求参数错误", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": {"type": "string", "description": "错误信息"} } }, "example": {"error": "无效的请求体"} } } }, "500": { "description": "服务器内部错误", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": {"type": "string", "description": "错误信息"} } }, "example": {"error": "更新黑名单列表失败"} } } } } } }, "/shield/localrules": { "get": { "summary": "获取本地规则", "description": "获取Shield的本地规则列表。", "tags": ["shield"], "responses": { "200": { "description": "成功获取本地规则", "content": { "application/json": { "schema": { "type": "array", "items": { "type": "object", "properties": { "id": {"type": "string", "description": "规则ID"}, "pattern": {"type": "string", "description": "规则模式"}, "description": {"type": "string", "description": "规则描述"} } } }, "example": [ {"id": "1", "pattern": ".*malware.*", "description": "恶意软件域名"} ] } } } } }, "post": { "summary": "添加本地规则", "description": "添加新的本地规则。", "tags": ["shield"], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "pattern": {"type": "string", "description": "规则模式"}, "description": {"type": "string", "description": "规则描述"} } }, "example": { "pattern": ".*ad\.com$", "description": "广告域名" } } } }, "responses": { "200": { "description": "成功添加规则", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": {"type": "string", "description": "操作状态"} } }, "example": {"status": "success"} } } } } }, "delete": { "summary": "删除本地规则", "description": "删除指定ID的本地规则。", "tags": ["shield"], "parameters": [ { "name": "id", "in": "query", "required": true, "schema": { "type": "string" }, "description": "规则ID" } ], "responses": { "200": { "description": "成功删除规则", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": {"type": "string", "description": "操作状态"} } }, "example": {"status": "success"} } } } } } }, "/shield/remoterules": { "get": { "summary": "获取远程规则", "description": "获取Shield的远程规则列表。", "tags": ["shield"], "responses": { "200": { "description": "成功获取远程规则", "content": { "application/json": { "schema": { "type": "array", "items": { "type": "object", "properties": { "id": {"type": "string", "description": "规则ID"}, "pattern": {"type": "string", "description": "规则模式"}, "source": {"type": "string", "description": "规则来源"} } } }, "example": [ {"id": "1001", "pattern": ".*phishing.*", "source": "malwarelist"} ] } } } } } }, "/shield/hosts": { "get": { "summary": "获取hosts列表", "description": "获取所有hosts记录。", "tags": ["shield"], "responses": { "200": { "description": "成功获取hosts列表", "content": { "application/json": { "schema": { "type": "array", "items": { "type": "object", "properties": { "ip": {"type": "string", "description": "IP地址"}, "domain": {"type": "string", "description": "域名"} } } }, "example": [ {"ip": "127.0.0.1", "domain": "localhost"} ] } } } } }, "post": { "summary": "添加hosts记录", "description": "添加新的hosts记录。", "tags": ["shield"], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": ["ip", "domain"], "properties": { "ip": {"type": "string", "description": "IP地址"}, "domain": {"type": "string", "description": "域名"} } }, "example": { "ip": "127.0.0.1", "domain": "example.com" } } } }, "responses": { "200": { "description": "成功添加hosts记录", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": {"type": "string", "description": "操作状态"} } }, "example": {"status": "success"} } } }, "400": { "description": "请求参数错误", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": {"type": "string", "description": "错误信息"} } }, "example": {"error": "IP和域名是必填项"} } } }, "500": { "description": "服务器内部错误", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": {"type": "string", "description": "错误信息"} } }, "example": {"error": "添加hosts记录失败"} } } } } }, "delete": { "summary": "删除hosts记录", "description": "删除指定域名的hosts记录。", "tags": ["shield"], "parameters": [ { "name": "domain", "in": "query", "required": true, "schema": { "type": "string" }, "description": "要删除的域名" } ], "responses": { "200": { "description": "成功删除hosts记录", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": {"type": "string", "description": "操作状态"} } }, "example": {"status": "success"} } } }, "400": { "description": "请求参数错误", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": {"type": "string", "description": "错误信息"} } }, "example": {"error": "域名是必填项"} } } }, "500": { "description": "服务器内部错误", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": {"type": "string", "description": "错误信息"} } }, "example": {"error": "删除hosts记录失败"} } } } } } }, "/query": { "get": { "summary": "检查域名是否被屏蔽", "description": "检查指定域名是否被Shield屏蔽,并返回详细的屏蔽信息,包括屏蔽规则、规则类型、来源等。", "tags": ["shield"], "parameters": [ { "name": "domain", "in": "query", "required": true, "schema": { "type": "string" }, "description": "要检查的域名" } ], "responses": { "200": { "description": "成功获取域名屏蔽信息", "content": { "application/json": { "schema": { "type": "object", "properties": { "domain": { "type": "string", "description": "检查的域名" }, "blocked": { "type": "boolean", "description": "是否被屏蔽" }, "blockRule": { "type": "string", "description": "屏蔽规则" }, "blockRuleType": { "type": "string", "description": "屏蔽规则类型" }, "blocksource": { "type": "string", "description": "屏蔽规则来源" }, "excluded": { "type": "boolean", "description": "是否被排除" }, "excludeRule": { "type": "string", "description": "排除规则" }, "excludeRuleType": { "type": "string", "description": "排除规则类型" }, "hasHosts": { "type": "boolean", "description": "是否有hosts记录" }, "hostsIP": { "type": "string", "description": "hosts记录中的IP" }, "timestamp": { "type": "string", "format": "date-time", "description": "查询时间戳" } } }, "example": { "domain": "example.com", "blocked": true, "blockRule": "example.com", "blockRuleType": "exact_domain", "blocksource": "本地规则", "excluded": false, "excludeRule": "", "excludeRuleType": "", "hasHosts": false, "hostsIP": "", "timestamp": "2023-07-15T14:30:45Z" } } } }, "400": { "description": "请求参数错误", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "description": "错误信息" } } }, "example": { "error": "Domain parameter is required" } } } } } } }, "/status": { "get": { "summary": "获取服务器状态", "description": "获取DNS服务器的状态信息。", "tags": ["server"], "responses": { "200": { "description": "成功获取服务器状态", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": {"type": "string", "description": "服务器状态"}, "uptime": {"type": "integer", "description": "运行时间(秒)"}, "version": {"type": "string", "description": "服务器版本"} } }, "example": { "status": "running", "uptime": 3600, "version": "1.0.0" } } } } } } }, "/config": { "get": { "summary": "获取服务器配置", "description": "获取DNS服务器的配置信息。", "tags": ["server"], "responses": { "200": { "description": "成功获取服务器配置", "content": { "application/json": { "schema": { "type": "object", "properties": { "port": {"type": "integer", "description": "服务器端口"}, "logLevel": {"type": "string", "description": "日志级别"} } }, "example": { "port": 53, "logLevel": "info" } } } } } }, "post": { "summary": "更新服务器配置", "description": "更新DNS服务器的配置信息。", "tags": ["server"], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "port": {"type": "integer", "description": "服务器端口"}, "logLevel": {"type": "string", "description": "日志级别"} } }, "example": { "port": 53, "logLevel": "info" } } } }, "responses": { "200": { "description": "成功更新服务器配置", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": {"type": "string", "description": "操作状态"} } }, "example": {"status": "success"} } } }, "400": { "description": "请求参数错误", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": {"type": "string", "description": "错误信息"} } }, "example": {"error": "参数格式错误"} } } }, "500": { "description": "服务器内部错误", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": {"type": "string", "description": "错误信息"} } }, "example": {"error": "更新配置失败"} } } } } } }, "/config/restart": { "post": { "summary": "重启服务器", "description": "重启DNS服务器。", "tags": ["server"], "responses": { "200": { "description": "成功重启服务器", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": {"type": "string", "description": "操作状态"} } }, "example": {"status": "success"} } } }, "500": { "description": "服务器内部错误", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": {"type": "string", "description": "错误信息"} } }, "example": {"error": "重启服务器失败"} } } } } } } }, "tags": [ { "name": "stats", "description": "统计相关API" }, { "name": "shield", "description": "Shield相关API" }, { "name": "server", "description": "服务器相关API" } ] }; // 初始化Swagger UI window.onload = function() { const ui = SwaggerUIBundle({ spec: swaggerDocument, dom_id: '#swagger-ui', deepLinking: true, presets: [ SwaggerUIBundle.presets.apis, SwaggerUIStandalonePreset ], plugins: [ SwaggerUIBundle.plugins.DownloadUrl ], layout: "StandaloneLayout" }); window.ui = ui; };