// 定义 API 文档的 JSON const swaggerDocument = { "openapi": "3.0.3", "info": { "title": "DNS Server API", "description": "DNS 服务器完整 API 文档，包括统计信息、Shield 管理、威胁查询等功能。", "version": "2.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:8081/api", "description": "本地开发服务器" }, { "url": "http://{host}:{port}/api", "description": "自定义服务器", "variables": { "host": { "default": "localhost" }, "port": { "default": "8081" } } } ], "paths": { "/threat": { "get": { "summary": "查询威胁域名信息", "description": "根据传入的域名参数查询威胁数据库，返回威胁类型、名称、风险等级和域名。数据来源于 threats-database.csv 文件。", "tags": ["threat"], "parameters": [ { "name": "domain", "in": "query", "required": true, "schema": { "type": "string" }, "description": "要查询的域名", "example": "kefubahaohonsheng.oss-cn-hongkong.aliyuncs.com" } ], "responses": { "200": { "description": "成功获取威胁信息或未找到威胁信息", "content": { "application/json": { "schema": { "oneOf": [ { "description": "找到威胁信息", "type": "object", "properties": { "data": { "type": "string", "description": "威胁信息，格式：类型，名称，风险等级，域名", "example": "钓鱼网站，Silver fox 团伙，2,kefubahaohonsheng.oss-cn-hongkong.aliyuncs.com" } } }, { "description": "未找到威胁信息", "type": "object", "properties": { "message": { "type": "string", "example": "无" } } } ] } } } }, "400": { "description": "请求参数错误 - 缺少域名参数", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "example": "需要提供 domain 参数" } } } } } }, "500": { "description": "服务器内部错误", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "example": "读取威胁数据库失败" } } } } } } } } }, "/query": { "get": { "summary": "查询域名屏蔽状态", "description": "查询指定域名的屏蔽状态和详细信息。", "tags": ["dns"], "parameters": [ { "name": "domain", "in": "query", "required": true, "schema": { "type": "string" }, "description": "要查询的域名" } ], "responses": { "200": { "description": "成功获取域名屏蔽状态", "content": { "application/json": { "schema": { "type": "object", "description": "域名屏蔽状态信息" } } } }, "400": { "description": "请求参数错误", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": {"type": "string", "description": "错误信息"} } }, "example": {"error": "需要提供 domain 参数"} } } } } } }, "/domains/{domain}": { "get": { "summary": "RESTful 风格域名查询", "description": "查询指定域名的屏蔽状态和详细信息。", "tags": ["dns"], "parameters": [ { "name": "domain", "in": "path", "required": true, "schema": { "type": "string" }, "description": "要查询的域名" } ], "responses": { "200": { "description": "成功获取域名信息", "content": { "application/json": { "schema": { "type": "object", "properties": { "domain": {"type": "string"}, "status": {"type": "boolean"}, "timestamp": {"type": "string"}, "details": {"type": "object"} } } } } } } } }, "/domain/info": { "post": { "summary": "查询域名详细信息", "description": "查询指定域名的详细信息，包括所属公司、类别等。", "tags": ["domain"], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "domain": {"type": "string", "description": "要查询的域名"} }, "required": ["domain"] }, "example": { "domain": "example.com" } } } }, "responses": { "200": { "description": "成功获取域名信息", "content": { "application/json": { "schema": { "type": "object", "description": "域名详细信息" } } } }, "400": { "description": "请求参数错误", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": {"type": "string", "description": "错误信息"} } }, "example": {"error": "Domain parameter is required"} } } }, "500": { "description": "服务器内部错误", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": {"type": "string", "description": "错误信息"} } }, "example": {"error": "Failed to query domain info"} } } } } } }, "/domain-info": { "get": { "summary": "获取域名信息列表", "description": "获取域名信息、跟踪器信息或威胁域名信息列表，支持过滤特定域名。", "tags": ["domain"], "parameters": [ { "name": "domains", "in": "query", "schema": { "type": "string" }, "description": "域名过滤条件" }, { "name": "trackers", "in": "query", "schema": { "type": "string" }, "description": "跟踪器过滤条件" }, { "name": "threats", "in": "query", "schema": { "type": "string" }, "description": "威胁域名过滤条件" } ], "responses": { "200": { "description": "成功获取域名信息列表", "content": { "application/json": { "schema": { "type": "array", "items": { "type": "object", "description": "域名信息项" } } } } }, "204": { "description": "无内容提供" }, "500": { "description": "服务器内部错误", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": {"type": "string", "description": "错误信息"} } } } } } } } }, "/stats": { "get": { "summary": "获取系统统计信息", "description": "获取 DNS 服务器和 Shield 的统计信息", "tags": ["stats"], "responses": { "200": { "description": "统计信息", "content": { "application/json": { "schema": { "type": "object", "properties": { "dns": {"type": "object"}, "shield": {"type": "object"}, "topQueryType": {"type": "string"}, "activeIPs": {"type": "integer"}, "avgResponseTime": {"type": "number"}, "cpuUsage": {"type": "number"}, "dnssecEnabled": {"type": "boolean"}, "time": {"type": "string"} } } } } } } } }, "/shield": { "get": { "summary": "获取 Shield 配置", "description": "获取 Shield 的配置信息", "tags": ["shield"], "responses": { "200": { "description": "配置信息", "content": { "application/json": { "schema": { "type": "object" } } } } } }, "post": { "summary": "添加屏蔽规则", "description": "添加新的域名屏蔽规则", "tags": ["shield"], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "rule": {"type": "string"} } } } } }, "responses": { "200": { "description": "操作成功", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": {"type": "string", "example": "success"} } } } } } } } }, "/status": { "get": { "summary": "获取系统状态", "description": "获取服务器的运行状态", "tags": ["server"], "responses": { "200": { "description": "系统状态信息", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": {"type": "string"}, "queries": {"type": "integer"}, "blocked": {"type": "integer"}, "uptime": {"type": "integer"} } } } } } } } }, "/config": { "get": { "summary": "获取系统配置", "description": "获取当前系统配置", "tags": ["server"], "responses": { "200": { "description": "配置信息", "content": { "application/json": { "schema": { "type": "object" } } } } } }, "post": { "summary": "更新系统配置", "description": "更新系统配置信息", "tags": ["server"], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object" } } } }, "responses": { "200": { "description": "配置更新成功", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": {"type": "boolean"}, "message": {"type": "string"} } } } } } } } }, "/logs/stats": { "get": { "summary": "获取日志统计", "description": "获取 DNS 查询日志的统计信息", "tags": ["logs"], "responses": { "200": { "description": "日志统计信息", "content": { "application/json": { "schema": { "type": "object" } } } } } } }, "/logs/query": { "get": { "summary": "查询日志", "description": "查询 DNS 查询日志", "tags": ["logs"], "parameters": [ { "name": "limit", "in": "query", "schema": { "type": "integer", "default": 100 }, "description": "返回日志数量" }, { "name": "offset", "in": "query", "schema": { "type": "integer", "default": 0 }, "description": "偏移量" }, { "name": "sort", "in": "query", "schema": { "type": "string" }, "description": "排序字段" }, { "name": "direction", "in": "query", "schema": { "type": "string" }, "description": "排序方向" }, { "name": "result", "in": "query", "schema": { "type": "string" }, "description": "结果过滤" }, { "name": "search", "in": "query", "schema": { "type": "string" }, "description": "搜索关键词" }, { "name": "queryType", "in": "query", "schema": { "type": "string" }, "description": "查询类型过滤" } ], "responses": { "200": { "description": "日志列表", "content": { "application/json": { "schema": { "type": "array" } } } } } } }, "/logs/count": { "get": { "summary": "获取日志总数", "description": "获取带过滤条件的 DNS 查询日志总数", "tags": ["logs"], "parameters": [ { "name": "result", "in": "query", "schema": { "type": "string" }, "description": "结果过滤" }, { "name": "search", "in": "query", "schema": { "type": "string" }, "description": "搜索关键词" }, { "name": "queryType", "in": "query", "schema": { "type": "string" }, "description": "查询类型过滤" } ], "responses": { "200": { "description": "日志总数", "content": { "application/json": { "schema": { "type": "object", "properties": { "count": { "type": "integer" } } } } } } } } }, "/login": { "post": { "summary": "用户登录", "description": "用户登录接口，验证用户名和密码", "tags": ["auth"], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "username": { "type": "string", "description": "用户名" }, "password": { "type": "string", "description": "密码" } }, "required": ["username", "password"] } } } }, "responses": { "200": { "description": "登录成功", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "example": "success" }, "message": { "type": "string", "example": "登录成功" } } } } } }, "400": { "description": "请求参数错误", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } } } } } }, "401": { "description": "用户名或密码错误", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } } } } } } } } }, "/logout": { "post": { "summary": "用户注销", "description": "用户注销接口，清除会话", "tags": ["auth"], "responses": { "200": { "description": "注销成功", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "example": "success" }, "message": { "type": "string", "example": "注销成功" } } } } } } } } }, "/change-password": { "post": { "summary": "修改密码", "description": "修改用户密码，需要认证", "tags": ["auth"], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "currentPassword": { "type": "string", "description": "当前密码" }, "newPassword": { "type": "string", "description": "新密码" } }, "required": ["currentPassword", "newPassword"] } } } }, "responses": { "200": { "description": "密码修改成功", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "example": "success" }, "message": { "type": "string", "example": "密码修改成功" } } } } } }, "400": { "description": "请求参数错误", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } } } } } }, "401": { "description": "当前密码错误或未授权", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } } } } } } } } }, "/shield/localrules": { "get": { "summary": "获取本地规则", "description": "获取自定义的屏蔽规则列表", "tags": ["shield"], "responses": { "200": { "description": "本地规则列表", "content": { "application/json": { "schema": { "type": "object", "properties": { "domainRules": { "type": "array", "items": { "type": "string" } }, "domainExceptions": { "type": "array", "items": { "type": "string" } }, "regexRules": { "type": "array", "items": { "type": "string" } }, "regexExceptions": { "type": "array", "items": { "type": "string" } }, "localRulesCount": { "type": "integer" } } } } } } } } }, "/shield/remoterules": { "get": { "summary": "获取远程规则", "description": "获取远程黑名单的规则列表", "tags": ["shield"], "responses": { "200": { "description": "远程规则列表", "content": { "application/json": { "schema": { "type": "object", "properties": { "domainRules": { "type": "array", "items": { "type": "string" } }, "domainExceptions": { "type": "array", "items": { "type": "string" } }, "regexRules": { "type": "array", "items": { "type": "string" } }, "regexExceptions": { "type": "array", "items": { "type": "string" } }, "remoteRulesCount": { "type": "integer" }, "blacklists": { "type": "array", "items": { "type": "object" } } } } } } } } } }, "/shield/hosts": { "get": { "summary": "获取 hosts 列表", "description": "获取所有 hosts 条目", "tags": ["shield"], "responses": { "200": { "description": "hosts 列表", "content": { "application/json": { "schema": { "type": "object", "properties": { "hosts": { "type": "array", "items": { "type": "object", "properties": { "domain": { "type": "string" }, "ip": { "type": "string" } } } }, "hostsCount": { "type": "integer" } } } } } } } }, "post": { "summary": "添加 hosts 条目", "description": "添加新的 hosts 映射记录", "tags": ["shield"], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "ip": { "type": "string", "description": "IP 地址" }, "domain": { "type": "string", "description": "域名" } }, "required": ["ip", "domain"] } } } }, "responses": { "200": { "description": "添加成功", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "example": "success" } } } } } }, "400": { "description": "请求参数错误", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } } } } } } } }, "delete": { "summary": "删除 hosts 条目", "description": "删除指定的 hosts 映射记录", "tags": ["shield"], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "domain": { "type": "string", "description": "要删除的域名" } }, "required": ["domain"] } } } }, "responses": { "200": { "description": "删除成功", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "example": "success" } } } } } } } } }, "/shield/blacklists": { "get": { "summary": "获取黑名单列表", "description": "获取所有远程黑名单配置列表", "tags": ["shield"], "responses": { "200": { "description": "黑名单列表", "content": { "application/json": { "schema": { "type": "array", "items": { "type": "object", "properties": { "url": { "type": "string", "description": "黑名单 URL" }, "name": { "type": "string", "description": "黑名单名称" }, "enabled": { "type": "boolean", "description": "是否启用" }, "lastUpdateTime": { "type": "string", "description": "最后更新时间" } } } } } } } } }, "post": { "summary": "添加黑名单", "description": "添加新的远程黑名单配置", "tags": ["shield"], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "url": { "type": "string", "description": "黑名单 URL" }, "name": { "type": "string", "description": "黑名单名称" }, "enabled": { "type": "boolean", "description": "是否启用", "default": true } }, "required": ["url", "name"] } } } }, "responses": { "200": { "description": "添加成功", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "example": "success" } } } } } }, "400": { "description": "请求参数错误", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } } } } } } } }, "put": { "summary": "更新黑名单", "description": "更新现有黑名单的最后更新时间", "tags": ["shield"], "parameters": [ { "name": "name", "in": "path", "required": true, "schema": { "type": "string" }, "description": "黑名单标识（URL 或名称）" } ], "responses": { "200": { "description": "更新成功", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "example": "success" } } } } } }, "404": { "description": "黑名单不存在", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } } } } } } } }, "delete": { "summary": "删除黑名单", "description": "删除指定的远程黑名单配置", "tags": ["shield"], "parameters": [ { "name": "name", "in": "path", "required": true, "schema": { "type": "string" }, "description": "黑名单标识（URL 或名称）" } ], "responses": { "200": { "description": "删除成功", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "example": "success" } } } } } } } } }, "/logs/stats": { "get": { "summary": "获取日志统计", "description": "获取 DNS 查询日志的统计信息，包括总查询数、屏蔽数、查询类型分布等", "tags": ["logs"], "responses": { "200": { "description": "日志统计信息", "content": { "application/json": { "schema": { "type": "object", "properties": { "totalQueries": { "type": "integer", "description": "总查询数" }, "blockedQueries": { "type": "integer", "description": "被屏蔽的查询数" }, "allowedQueries": { "type": "integer", "description": "允许的查询数" }, "queryTypeStats": { "type": "object", "description": "查询类型统计" }, "topDomains": { "type": "array", "items": { "type": "object" }, "description": "TOP 域名列表" }, "topClients": { "type": "array", "items": { "type": "object" }, "description": "TOP 客户端列表" } } } } } } } } }, "/config/restart": { "post": { "summary": "重启服务", "description": "重启 DNS 服务和屏蔽规则更新", "tags": ["server"], "responses": { "200": { "description": "重启成功", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "example": "success" }, "message": { "type": "string", "example": "服务已重启" } } } } } } } } }, "/top-blocked": { "get": { "summary": "获取最常屏蔽域名", "description": "获取最近 30 天内最常被屏蔽的域名列表", "tags": ["stats"], "responses": { "200": { "description": "TOP 屏蔽域名列表", "content": { "application/json": { "schema": { "type": "array", "items": { "type": "object", "properties": { "domain": { "type": "string" }, "count": { "type": "integer" } } } } } } } } } }, "/top-resolved": { "get": { "summary": "获取最常解析域名", "description": "获取最近 30 天内最常被解析的域名列表", "tags": ["stats"], "responses": { "200": { "description": "TOP 解析域名列表", "content": { "application/json": { "schema": { "type": "array", "items": { "type": "object", "properties": { "domain": { "type": "string" }, "count": { "type": "integer" } } } } } } } } } }, "/top-clients": { "get": { "summary": "获取 TOP 客户端", "description": "获取最活跃的 DNS 查询客户端 IP 列表", "tags": ["stats"], "responses": { "200": { "description": "TOP 客户端列表", "content": { "application/json": { "schema": { "type": "array", "items": { "type": "object", "properties": { "ip": { "type": "string" }, "count": { "type": "integer" }, "lastSeen": { "type": "string" } } } } } } } } } }, "/top-domains": { "get": { "summary": "获取 TOP 域名", "description": "获取最近 30 天内查询最频繁的域名列表（包括屏蔽和解析）", "tags": ["stats"], "responses": { "200": { "description": "TOP 域名列表", "content": { "application/json": { "schema": { "type": "array", "items": { "type": "object", "properties": { "domain": { "type": "string" }, "count": { "type": "integer" }, "dnssec": { "type": "boolean" } } } } } } } } } }, "/recent-blocked": { "get": { "summary": "获取最近屏蔽域名", "description": "获取最近被屏蔽的域名列表", "tags": ["stats"], "responses": { "200": { "description": "最近屏蔽域名列表", "content": { "application/json": { "schema": { "type": "array", "items": { "type": "object", "properties": { "domain": { "type": "string" }, "time": { "type": "string" } } } } } } } } } }, "/hourly-stats": { "get": { "summary": "获取 24 小时统计", "description": "获取最近 24 小时的 DNS 查询统计", "tags": ["stats"], "responses": { "200": { "description": "24 小时统计数据", "content": { "application/json": { "schema": { "type": "object", "properties": { "labels": { "type": "array", "items": { "type": "string" } }, "data": { "type": "array", "items": { "type": "integer" } } } } } } } } } }, "/daily-stats": { "get": { "summary": "获取每日统计", "description": "获取过去 7 天的 DNS 查询统计", "tags": ["stats"], "responses": { "200": { "description": "每日统计数据", "content": { "application/json": { "schema": { "type": "object", "properties": { "labels": { "type": "array", "items": { "type": "string" } }, "data": { "type": "array", "items": { "type": "integer" } } } } } } } } } }, "/monthly-stats": { "get": { "summary": "获取每月统计", "description": "获取过去 30 天的 DNS 查询统计", "tags": ["stats"], "responses": { "200": { "description": "每月统计数据", "content": { "application/json": { "schema": { "type": "object", "properties": { "labels": { "type": "array", "items": { "type": "string" } }, "data": { "type": "array", "items": { "type": "integer" } } } } } } } } } }, "/query/type": { "get": { "summary": "获取查询类型统计", "description": "获取 DNS 查询类型的分布统计", "tags": ["stats"], "responses": { "200": { "description": "查询类型统计数据", "content": { "application/json": { "schema": { "type": "array", "items": { "type": "object", "properties": { "type": { "type": "string" }, "count": { "type": "integer" } } } } } } } } } }, "/threat/batch": { "post": { "summary": "批量查询威胁域名", "description": "批量查询多个域名是否是威胁域名", "tags": ["threat"], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "domains": { "type": "array", "items": { "type": "string" }, "description": "域名列表" } }, "required": ["domains"] } } } }, "responses": { "200": { "description": "批量查询结果", "content": { "application/json": { "schema": { "type": "object", "properties": { "results": { "type": "array", "items": { "type": "object", "properties": { "domain": { "type": "string" }, "isThreat": { "type": "boolean" }, "data": { "type": "string", "description": "威胁信息（如果是威胁）" } } } } } } } } } } } } }, "tags": [ { "name": "auth", "description": "认证相关 API - 包括登录、注销、修改密码等功能" }, { "name": "stats", "description": "统计相关 API - 包括 DNS 查询统计、TOP 域名、客户端统计等" }, { "name": "shield", "description": "Shield 相关 API - 包括屏蔽规则管理、hosts 管理、本地/远程规则查询等" }, { "name": "threat", "description": "威胁域名查询 API - 提供威胁域名数据库查询和批量查询功能" }, { "name": "server", "description": "服务器相关 API - 包括系统状态、配置管理、服务重启等" }, { "name": "logs", "description": "日志相关 API - 包括日志查询、统计、计数等" }, { "name": "dns", "description": "DNS 相关 API - 包括域名查询、域名屏蔽状态查询等" }, { "name": "domain", "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; };