{ "openapi": "3.0.0", "info": { "title": "透析机IoT数据服务 HTTP API", "description": "透析机设备实时数据查询和管理接口", "version": "1.1.0", "contact": { "name": "技术支持", "email": "support@example.com" }, "license": { "name": "MIT" } }, "servers": [ { "url": "http://localhost:8080", "description": "开发环境" }, { "url": "http://production-server:8080", "description": "生产环境" } ], "paths": { "/api/health": { "get": { "summary": "健康检查", "description": "检查服务器是否正常运行", "operationId": "getHealth", "tags": ["系统"], "responses": { "200": { "description": "服务正常", "content": { "application/json": { "schema": { "type": "object", "properties": { "code": { "type": "integer", "example": 200 }, "message": { "type": "string", "example": "success" }, "data": { "type": "object", "properties": { "status": { "type": "string", "example": "ok" }, "timestamp": { "type": "string", "format": "date-time" } } } } } } } }, "500": { "description": "服务不可用" } } } }, "/api/device/data": { "get": { "summary": "获取单个设备数据", "description": "获取指定设备的实时数据。支持原始格式和映射格式（推荐）", "operationId": "getDeviceData", "tags": ["设备数据"], "parameters": [ { "name": "deviceNumber", "in": "query", "description": "设备号，例如 D001", "required": true, "schema": { "type": "string" } }, { "name": "mapped", "in": "query", "description": "是否返回映射格式（推荐使用 true）", "required": false, "schema": { "type": "string", "enum": ["true", "false"], "default": "false" } } ], "responses": { "200": { "description": "成功获取设备数据", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DeviceDataResponse" } } } }, "400": { "description": "参数错误" }, "404": { "description": "设备不存在" }, "429": { "description": "请求过于频繁，请稍后再试" } }, "x-rate-limit": { "interval": "5秒", "max-requests": 1 } } }, "/api/device/all": { "get": { "summary": "获取所有设备数据", "description": "批量获取所有设备的实时数据", "operationId": "getAllDevices", "tags": ["设备数据"], "parameters": [ { "name": "mapped", "in": "query", "description": "是否返回映射格式（推荐使用 true）", "required": false, "schema": { "type": "string", "enum": ["true", "false"], "default": "false" } } ], "responses": { "200": { "description": "成功获取所有设备数据", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AllDevicesResponse" } } } }, "429": { "description": "请求过于频繁，请稍后再试" } }, "x-rate-limit": { "interval": "60秒", "max-requests": 1 } } }, "/api/device/list": { "get": { "summary": "获取设备列表", "description": "获取所有已连接设备的摘要信息", "operationId": "getDeviceList", "tags": ["设备数据"], "responses": { "200": { "description": "成功获取设备列表", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DeviceListResponse" } } } } } } }, "/api/device/idle": { "get": { "summary": "获取超时设备", "description": "获取超过指定时间未更新的设备列表", "operationId": "getIdleDevices", "tags": ["设备数据"], "parameters": [ { "name": "timeout", "in": "query", "description": "超时时间（毫秒），例如 300000（5分钟）", "required": false, "schema": { "type": "integer", "default": 300000 } } ], "responses": { "200": { "description": "成功获取超时设备列表", "content": { "application/json": { "schema": { "type": "object", "properties": { "code": { "type": "integer" }, "message": { "type": "string" }, "data": { "type": "object", "properties": { "timeout": { "type": "integer" }, "idleDevices": { "type": "array", "items": { "type": "string" } } } } } } } } } } } }, "/api/cache/stats": { "get": { "summary": "获取缓存统计", "description": "获取数据缓存的统计信息", "operationId": "getCacheStats", "tags": ["统计"], "responses": { "200": { "description": "成功获取缓存统计", "content": { "application/json": { "schema": { "type": "object", "properties": { "code": { "type": "integer" }, "message": { "type": "string" }, "data": { "type": "object", "properties": { "timestamp": { "type": "string", "format": "date-time" }, "totalDevices": { "type": "integer" }, "cachedProperties": { "type": "integer" }, "cacheSize": { "type": "string" }, "oldestData": { "type": "string", "format": "date-time" }, "newestData": { "type": "string", "format": "date-time" } } } } } } } } } } }, "/api/ratelimit/stats": { "get": { "summary": "获取限流统计", "description": "获取请求限流的统计信息", "operationId": "getRateLimitStats", "tags": ["统计"], "responses": { "200": { "description": "成功获取限流统计", "content": { "application/json": { "schema": { "type": "object", "properties": { "code": { "type": "integer" }, "message": { "type": "string" }, "data": { "type": "object", "properties": { "enabled": { "type": "boolean" }, "interval": { "type": "integer", "description": "单个设备限流间隔（毫秒）" }, "allDevicesInterval": { "type": "integer", "description": "全局限流间隔（毫秒）" }, "records": { "type": "array", "items": { "type": "object", "properties": { "identifier": { "type": "string" }, "lastRequest": { "type": "string", "format": "date-time" }, "requestCount": { "type": "integer" } } } } } } } } } } } } } }, "/api/cache/clear": { "post": { "summary": "清空缓存", "description": "清空所有缓存的设备数据（需谨慎使用）", "operationId": "clearCache", "tags": ["缓存管理"], "responses": { "200": { "description": "缓存已清空", "content": { "application/json": { "schema": { "type": "object", "properties": { "code": { "type": "integer" }, "message": { "type": "string" }, "data": { "type": "object", "properties": { "message": { "type": "string" } } } } } } } } } } }, "/api/ratelimit/clear": { "post": { "summary": "清空限流记录", "description": "清空所有限流记录", "operationId": "clearRateLimit", "tags": ["缓存管理"], "responses": { "200": { "description": "限流记录已清空", "content": { "application/json": { "schema": { "type": "object", "properties": { "code": { "type": "integer" }, "message": { "type": "string" }, "data": { "type": "object", "properties": { "message": { "type": "string" } } } } } } } } } } } }, "components": { "schemas": { "DeviceProperty": { "type": "object", "properties": { "identifier": { "type": "string", "description": "属性标识符", "example": "A" }, "name": { "type": "string", "description": "属性中文名称", "example": "脱水目标量" }, "value": { "type": "string", "description": "属性值", "example": "50" } } }, "DeviceDataResponse": { "type": "object", "properties": { "code": { "type": "integer", "example": 200 }, "message": { "type": "string", "example": "success" }, "data": { "type": "object", "properties": { "deviceNumber": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "properties": { "type": "array", "items": { "$ref": "#/components/schemas/DeviceProperty" } }, "format": { "type": "string", "enum": ["raw", "mapped"] } } } } }, "AllDevicesResponse": { "type": "object", "properties": { "code": { "type": "integer" }, "message": { "type": "string" }, "data": { "type": "object", "properties": { "count": { "type": "integer" }, "data": { "type": "object", "additionalProperties": { "type": "object", "properties": { "timestamp": { "type": "string", "format": "date-time" }, "properties": { "type": "array", "items": { "$ref": "#/components/schemas/DeviceProperty" } }, "format": { "type": "string" } } } }, "format": { "type": "string" } } } } }, "DeviceListResponse": { "type": "object", "properties": { "code": { "type": "integer" }, "message": { "type": "string" }, "data": { "type": "object", "properties": { "count": { "type": "integer" }, "devices": { "type": "array", "items": { "type": "object", "properties": { "deviceNumber": { "type": "string" }, "lastUpdate": { "type": "string", "format": "date-time" } } } } } } } } } }, "tags": [ { "name": "系统", "description": "系统级别的API" }, { "name": "设备数据", "description": "设备数据查询接口" }, { "name": "统计", "description": "统计信息接口" }, { "name": "缓存管理", "description": "缓存和限流管理" } ] }