From 43f01338862aef9b9219af7cf01731be37bae7dc Mon Sep 17 00:00:00 2001 From: Alex Yang Date: Fri, 26 Dec 2025 09:27:39 +0800 Subject: [PATCH] =?UTF-8?q?=E6=9B=B4=E6=96=B0Swagger=20API?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- CHANGELOG.md | 2 + static/api/js/index.js | 161 ++++++++++++++++++++--------------------- 2 files changed, 79 insertions(+), 84 deletions(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index fa32364..05b31ee 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -19,6 +19,8 @@ - 修复查询日志详情接口返回的日志中，解析记录中缺少IP地址、类型、DNSSEC验证状态等信息的问题； - web界面系统设置加载后不获取数据和保存配置不生效的问题； - 修复了DNS查询超时设置过短导致的"Server failed"错误。 +### 更新 +- 更新Swagger API文档。 ### 下一版本改进 - 增加了对DNSSEC的支持配置项，默认关闭； diff --git a/static/api/js/index.js b/static/api/js/index.js index 94fa52e..9addc52 100644 --- a/static/api/js/index.js +++ b/static/api/js/index.js @@ -4,7 +4,7 @@ "info": { "title": "DNS Server API", "description": "DNS服务器完整API文档，包括统计信息、Shield管理、主机管理等功能。", - "version": "1.1.0", + "version": "1.2.5", "contact": { "name": "DNS Server 支持", "email": "support@dnsserver.com" @@ -713,6 +713,7 @@ "get": { "summary": "获取Shield配置和统计信息", "description": "获取Shield的配置信息和规则统计，包括更新间隔、屏蔽方法、黑名单数量等。", + "deprecated": false, "tags": ["shield"], "responses": { "200": { @@ -764,6 +765,7 @@ "post": { "summary": "添加屏蔽规则", "description": "添加新的屏蔽规则到Shield。", + "deprecated": false, "tags": ["shield"], "requestBody": { "required": true, @@ -829,6 +831,7 @@ "delete": { "summary": "删除屏蔽规则", "description": "从Shield中删除指定的屏蔽规则。", + "deprecated": false, "tags": ["shield"], "requestBody": { "required": true, @@ -894,6 +897,7 @@ "put": { "summary": "重新加载规则", "description": "重新加载和应用Shield规则。", + "deprecated": false, "tags": ["shield"], "responses": { "200": { @@ -934,7 +938,8 @@ "/shield/blacklists": { "get": { "summary": "获取黑名单列表", - "description": "获取所有远程黑名单的列表及详细信息。", + "description": "获取Shield的黑名单列表，包括内置黑名单和自定义黑名单。", + "deprecated": false, "tags": ["shield"], "responses": { "200": { @@ -986,7 +991,8 @@ }, "post": { "summary": "添加黑名单", - "description": "添加新的远程黑名单URL。", + "description": "添加新的黑名单URL到Shield。", + "deprecated": false, "tags": ["shield"], "requestBody": { "required": true, @@ -1057,6 +1063,7 @@ "put": { "summary": "更新黑名单列表（包括启用/禁用状态）", "description": "更新黑名单列表（包括启用/禁用状态）。", + "deprecated": false, "tags": ["shield"], "requestBody": { "required": true, @@ -1139,7 +1146,8 @@ "/shield/localrules": { "get": { "summary": "获取自定义规则", - "description": "获取Shield的自定义规则列表。" + "description": "获取Shield的自定义规则列表。", + "deprecated": false, "tags": ["shield"], "responses": { "200": { @@ -1168,6 +1176,7 @@ "post": { "summary": "添加自定义规则", "description": "添加新的自定义规则。", + "deprecated": false, "tags": ["shield"], "requestBody": { "required": true, @@ -1206,7 +1215,8 @@ }, "delete": { "summary": "删除自定义规则", - "description": "删除指定ID的自定义规则。", + "description": "删除指定的自定义规则。", + "deprecated": false, "tags": ["shield"], "parameters": [ { @@ -1239,8 +1249,9 @@ }, "/shield/remoterules": { "get": { - "summary": "获取远程规则", - "description": "获取Shield的远程规则列表。", + "summary": "获取远程规则状态", + "description": "获取远程规则的更新状态和版本信息。", + "deprecated": false, "tags": ["shield"], "responses": { "200": { @@ -1269,8 +1280,9 @@ }, "/shield/hosts": { "get": { - "summary": "获取hosts列表", - "description": "获取所有hosts记录。", + "summary": "获取hosts内容", + "description": "获取当前的hosts文件内容。", + "deprecated": false, "tags": ["shield"], "responses": { "200": { @@ -1298,6 +1310,7 @@ "post": { "summary": "添加hosts记录", "description": "添加新的hosts记录。", + "deprecated": false, "tags": ["shield"], "requestBody": { "required": true, @@ -1366,6 +1379,7 @@ "delete": { "summary": "删除hosts记录", "description": "删除指定域名的hosts记录。", + "deprecated": false, "tags": ["shield"], "parameters": [ { @@ -1424,90 +1438,69 @@ } } }, - "/query": { - "get": { - "summary": "检查域名是否被屏蔽", - "description": "检查指定域名是否被Shield屏蔽，并返回详细的屏蔽信息，包括屏蔽规则、规则类型、来源等。", - "tags": ["shield"], - "parameters": [ - { - "name": "domain", - "in": "query", - "required": true, - "schema": { - "type": "string" - }, - "description": "要检查的域名" + "/dns/query": { + "post": { + "summary": "查询DNS记录", + "description": "查询指定域名的DNS记录，可以指定记录类型。", + "tags": ["dns"], + "requestBody": { + "required": true, + "content": { + "application/json": { + "schema": { + "type": "object", + "properties": { + "domain": { + "type": "string", + "description": "要查询的域名" + }, + "recordType": { + "type": "string", + "description": "DNS记录类型（如A、AAAA、MX、NS等）" + } + }, + "required": ["domain"] + }, + "example": { + "domain": "example.com", + "recordType": "A" + } + } } - ], + }, "responses": { "200": { - "description": "成功获取域名屏蔽信息", + "description": "成功获取DNS记录", "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": "查询时间戳" + "type": "array", + "items": { + "type": "object", + "properties": { + "Type": { + "type": "string", + "description": "DNS记录类型" + }, + "Value": { + "type": "string", + "description": "DNS记录值" + }, + "TTL": { + "type": "integer", + "description": "生存时间" + }, + "Preference": { + "type": "integer", + "description": "MX记录优先级" + } } } }, - "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" - } + "example": [ + {"Type": "A", "Value": "93.184.216.34", "TTL": 172800}, + {"Type": "A", "Value": "93.184.216.35", "TTL": 172800} + ] } } },