1.修改部分代码风格，实现风格统一 2.添加数据刷新时间到config中 3.将html单独放到文件中并且添加一些相关说明
This commit is contained in:
670
gateway/templates/api_doc.html
Normal file
670
gateway/templates/api_doc.html
Normal file
@ -0,0 +1,670 @@
|
||||
<html>
|
||||
<head>
|
||||
<title>PLC Gateway API Documentation</title>
|
||||
<style>
|
||||
body { font-family: Arial, sans-serif; margin: 20px; }
|
||||
h1, h2, h3 { color: #2c3e50; }
|
||||
.endpoint {
|
||||
background-color: #f8f9fa;
|
||||
border-left: 4px solid #3498db;
|
||||
padding: 15px;
|
||||
margin: 20px 0;
|
||||
border-radius: 4px;
|
||||
}
|
||||
.method {
|
||||
display: inline-block;
|
||||
padding: 3px 8px;
|
||||
border-radius: 4px;
|
||||
color: white;
|
||||
font-weight: bold;
|
||||
margin-right: 10px;
|
||||
}
|
||||
.method-get { background-color: #27ae60; }
|
||||
.method-post { background-color: #3498db; }
|
||||
.method-put { background-color: #f39c12; }
|
||||
.method-delete { background-color: #e74c3c; }
|
||||
table {
|
||||
border-collapse: collapse;
|
||||
width: 100%;
|
||||
margin: 15px 0;
|
||||
}
|
||||
th, td {
|
||||
border: 1px solid #ddd;
|
||||
padding: 8px;
|
||||
text-align: left;
|
||||
}
|
||||
th {
|
||||
background-color: #f2f2f2;
|
||||
}
|
||||
code {
|
||||
background-color: #f5f5f5;
|
||||
padding: 2px 4px;
|
||||
border-radius: 3px;
|
||||
font-family: monospace;
|
||||
}
|
||||
.example {
|
||||
background-color: #f9f9f9;
|
||||
padding: 10px;
|
||||
border-radius: 4px;
|
||||
margin: 10px 0;
|
||||
font-family: monospace;
|
||||
}
|
||||
.nav {
|
||||
background-color: #e9f7fe;
|
||||
padding: 10px;
|
||||
border-radius: 4px;
|
||||
margin-bottom: 20px;
|
||||
}
|
||||
.nav a {
|
||||
margin-right: 15px;
|
||||
text-decoration: none;
|
||||
color: #3498db;
|
||||
}
|
||||
</style>
|
||||
</head>
|
||||
<body>
|
||||
<h1>PLC Gateway API Documentation</h1>
|
||||
|
||||
<div class="nav">
|
||||
<a href="#status-api">Status API</a> |
|
||||
<a href="#data-api">Data API</a> |
|
||||
<a href="#config-api">Configuration API</a>
|
||||
</div>
|
||||
|
||||
<h2 id="status-api">Status API</h2>
|
||||
|
||||
<div class="endpoint">
|
||||
<h3>System Status</h3>
|
||||
<div>
|
||||
<span class="method method-get">GET</span>
|
||||
<code>/api/status</code>
|
||||
</div>
|
||||
<p>获取系统状态信息，包括启动时间、PLC数量和缓存大小。</p>
|
||||
|
||||
<h4>响应示例</h4>
|
||||
<div class="example">
|
||||
{
|
||||
"status": "running",
|
||||
"start_time": "2023-10-30 14:30:22",
|
||||
"plc_count": 2,
|
||||
"cache_size": 11000,
|
||||
"plc_statuses": {
|
||||
"PLC1": {
|
||||
"status": "connected",
|
||||
"last_connected": "2023-10-30 14:35:10"
|
||||
},
|
||||
"PLC2": {
|
||||
"status": "disconnected",
|
||||
"last_connected": "Never"
|
||||
}
|
||||
}
|
||||
}
|
||||
</div>
|
||||
</div>
|
||||
|
||||
<div class="endpoint">
|
||||
<h3>Area Status</h3>
|
||||
<div>
|
||||
<span class="method method-get">GET</span>
|
||||
<code>/api/status/<plc_name>/<area_name></code>
|
||||
</div>
|
||||
<p>获取指定PLC区域的状态信息。</p>
|
||||
|
||||
<h4>路径参数</h4>
|
||||
<table>
|
||||
<tr>
|
||||
<th>参数</th>
|
||||
<th>描述</th>
|
||||
</tr>
|
||||
<tr>
|
||||
<td>plc_name</td>
|
||||
<td>PLC名称（如PLC1）</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td>area_name</td>
|
||||
<td>区域名称（如DB100_Read）</td>
|
||||
</tr>
|
||||
</table>
|
||||
|
||||
<h4>响应示例</h4>
|
||||
<div class="example">
|
||||
{
|
||||
"status": "connected",
|
||||
"plc_connection_status": "connected",
|
||||
"last_update": 1698754321.456,
|
||||
"last_update_formatted": "2023-10-30 14:12:01",
|
||||
"size": 4000,
|
||||
"type": "read"
|
||||
}
|
||||
</div>
|
||||
</div>
|
||||
|
||||
<h2 id="data-api">Data API</h2>
|
||||
|
||||
<div class="endpoint">
|
||||
<h3>Single Read</h3>
|
||||
<div>
|
||||
<span class="method method-get">GET</span>
|
||||
<code>/api/read/<plc_name>/<area_name>/<offset>/<length></code>
|
||||
</div>
|
||||
<p>从指定区域读取数据。</p>
|
||||
|
||||
<h4>路径参数</h4>
|
||||
<table>
|
||||
<tr>
|
||||
<th>参数</th>
|
||||
<th>描述</th>
|
||||
</tr>
|
||||
<tr>
|
||||
<td>plc_name</td>
|
||||
<td>PLC名称（如PLC1）</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td>area_name</td>
|
||||
<td>区域名称（如DB100_Read）</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td>offset</td>
|
||||
<td>起始偏移量（字节）</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td>length</td>
|
||||
<td>读取长度（字节）</td>
|
||||
</tr>
|
||||
</table>
|
||||
|
||||
<h4>响应示例</h4>
|
||||
<div class="example">
|
||||
{
|
||||
"status": "success",
|
||||
"plc_name": "PLC1",
|
||||
"area_name": "DB100_Read",
|
||||
"offset": 0,
|
||||
"length": 4,
|
||||
"data": [0, 0, 123, 45],
|
||||
"plc_connection_status": "connected",
|
||||
"last_update": 1698754321.456,
|
||||
"last_update_formatted": "2023-10-30 14:12:01"
|
||||
}
|
||||
</div>
|
||||
</div>
|
||||
|
||||
<div class="endpoint">
|
||||
<h3>Single Write</h3>
|
||||
<div>
|
||||
<span class="method method-post">POST</span>
|
||||
<code>/api/write/<plc_name>/<area_name>/<offset></code>
|
||||
</div>
|
||||
<p>向指定区域写入数据。</p>
|
||||
|
||||
<h4>路径参数</h4>
|
||||
<table>
|
||||
<tr>
|
||||
<th>参数</th>
|
||||
<th>描述</th>
|
||||
</tr>
|
||||
<tr>
|
||||
<td>plc_name</td>
|
||||
<td>PLC名称（如PLC1）</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td>area_name</td>
|
||||
<td>区域名称（如DB100_Write）</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td>offset</td>
|
||||
<td>起始偏移量（字节）</td>
|
||||
</tr>
|
||||
</table>
|
||||
|
||||
<h4>请求体</h4>
|
||||
<p>原始二进制数据</p>
|
||||
|
||||
<h4>响应示例</h4>
|
||||
<div class="example">
|
||||
{
|
||||
"status": "success",
|
||||
"plc_name": "PLC1",
|
||||
"area_name": "DB100_Write",
|
||||
"offset": 0,
|
||||
"length": 4,
|
||||
"plc_connection_status": "connected",
|
||||
"last_update": 1698754350.789,
|
||||
"last_update_formatted": "2023-10-30 14:12:30"
|
||||
}
|
||||
</div>
|
||||
</div>
|
||||
|
||||
<div class="endpoint">
|
||||
<h3>Single Read Bool</h3>
|
||||
<div>
|
||||
<span class="method method-get">GET</span>
|
||||
<code>/api/read_bool/<plc_name>/<area_name>/<offset>/<length></code>
|
||||
</div>
|
||||
<p>从指定区域读取数据。</p>
|
||||
|
||||
<h4>路径参数</h4>
|
||||
<table>
|
||||
<tr>
|
||||
<th>参数</th>
|
||||
<th>描述</th>
|
||||
</tr>
|
||||
<tr>
|
||||
<td>plc_name</td>
|
||||
<td>PLC名称（如PLC1）</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td>area_name</td>
|
||||
<td>区域名称（如DB100_Read）</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td>offset</td>
|
||||
<td>起始偏移量（字节）</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td>length</td>
|
||||
<td>读取长度（字节）</td>
|
||||
</tr>
|
||||
</table>
|
||||
|
||||
<h4>响应示例</h4>
|
||||
<div class="example">
|
||||
{
|
||||
"status": "success",
|
||||
"plc_name": "PLC1",
|
||||
"area_name": "DB100_Read",
|
||||
"offset": 0,
|
||||
"length": 2,
|
||||
"data": [0:False, 1:False],
|
||||
"plc_connection_status": "connected",
|
||||
"last_update": 1698754321.456,
|
||||
"last_update_formatted": "2023-10-30 14:12:01"
|
||||
}
|
||||
</div>
|
||||
</div>
|
||||
|
||||
<div class="endpoint">
|
||||
<h3>Single Write Bool</h3>
|
||||
<div>
|
||||
<span class="method method-post">POST</span>
|
||||
<code>/api/write_bool/<plc_name>/<area_name>/<offset></code>
|
||||
</div>
|
||||
<p>向指定区域写入数据。</p>
|
||||
|
||||
<h4>路径参数</h4>
|
||||
<table>
|
||||
<tr>
|
||||
<th>参数</th>
|
||||
<th>描述</th>
|
||||
</tr>
|
||||
<tr>
|
||||
<td>plc_name</td>
|
||||
<td>PLC名称（如PLC1）</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td>area_name</td>
|
||||
<td>区域名称（如DB100_Write）</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td>offset</td>
|
||||
<td>起始偏移量（字节）</td>
|
||||
</tr>
|
||||
</table>
|
||||
|
||||
<h4>请求体</h4>
|
||||
<p>{0:True}</p>
|
||||
|
||||
<h4>响应示例</h4>
|
||||
<div class="example">
|
||||
{
|
||||
"status": "success",
|
||||
"plc_name": "PLC1",
|
||||
"area_name": "DB100_Write",
|
||||
"offset": 0,
|
||||
"length": 1,
|
||||
"plc_connection_status": "connected",
|
||||
"last_update": 1698754350.789,
|
||||
"last_update_formatted": "2023-10-30 14:12:30"
|
||||
}
|
||||
</div>
|
||||
</div>
|
||||
|
||||
<div class="endpoint">
|
||||
<h3>Batch Read</h3>
|
||||
<div>
|
||||
<span class="method method-post">POST</span>
|
||||
<code>/api/batch_read</code>
|
||||
</div>
|
||||
<p>批量读取多个区域的数据。</p>
|
||||
|
||||
<h4>请求体</h4>
|
||||
<table>
|
||||
<tr>
|
||||
<th>字段</th>
|
||||
<th>类型</th>
|
||||
<th>必需</th>
|
||||
<th>描述</th>
|
||||
</tr>
|
||||
<tr>
|
||||
<td>plc_name</td>
|
||||
<td>string</td>
|
||||
<td>是</td>
|
||||
<td>PLC名称（与配置中一致）</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td>area_name</td>
|
||||
<td>string</td>
|
||||
<td>是</td>
|
||||
<td>区域名称（与配置中一致）</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td>offset</td>
|
||||
<td>number</td>
|
||||
<td>否</td>
|
||||
<td>起始偏移量（字节），默认为0</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td>length</td>
|
||||
<td>number</td>
|
||||
<td>否</td>
|
||||
<td>读取长度（字节），不提供则读取整个区域</td>
|
||||
</tr>
|
||||
</table>
|
||||
|
||||
<h4>请求示例</h4>
|
||||
<div class="example">
|
||||
[
|
||||
{
|
||||
"plc_name": "PLC1",
|
||||
"area_name": "DB100_Read",
|
||||
"offset": 0,
|
||||
"length": 4
|
||||
},
|
||||
{
|
||||
"plc_name": "PLC1",
|
||||
"area_name": "DB202_Params",
|
||||
"offset": 10,
|
||||
"length": 2
|
||||
}
|
||||
]
|
||||
</div>
|
||||
|
||||
<h4>响应示例</h4>
|
||||
<div class="example">
|
||||
[
|
||||
{
|
||||
"plc_name": "PLC1",
|
||||
"area_name": "DB100_Read",
|
||||
"status": "success",
|
||||
"plc_connection_status": "connected",
|
||||
"last_update": 1698754321.456,
|
||||
"last_update_formatted": "2023-10-30 14:12:01",
|
||||
"offset": 0,
|
||||
"length": 4,
|
||||
"data": [0, 0, 123, 45]
|
||||
},
|
||||
{
|
||||
"plc_name": "PLC1",
|
||||
"area_name": "DB202_Params",
|
||||
"status": "success",
|
||||
"plc_connection_status": "connected",
|
||||
"last_update": 1698754322.123,
|
||||
"last_update_formatted": "2023-10-30 14:12:02",
|
||||
"offset": 10,
|
||||
"length": 2,
|
||||
"data": [255, 0]
|
||||
}
|
||||
]
|
||||
</div>
|
||||
</div>
|
||||
|
||||
<div class="endpoint">
|
||||
<h3>Batch Write</h3>
|
||||
<div>
|
||||
<span class="method method-post">POST</span>
|
||||
<code>/api/batch_write</code>
|
||||
</div>
|
||||
<p>批量写入多个区域的数据。</p>
|
||||
|
||||
<h4>请求体</h4>
|
||||
<table>
|
||||
<tr>
|
||||
<th>字段</th>
|
||||
<th>类型</th>
|
||||
<th>必需</th>
|
||||
<th>描述</th>
|
||||
</tr>
|
||||
<tr>
|
||||
<td>plc_name</td>
|
||||
<td>string</td>
|
||||
<td>是</td>
|
||||
<td>PLC名称（与配置中一致）</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td>area_name</td>
|
||||
<td>string</td>
|
||||
<td>是</td>
|
||||
<td>区域名称（与配置中一致）</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td>offset</td>
|
||||
<td>number</td>
|
||||
<td>是</td>
|
||||
<td>起始偏移量（字节）</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td>data</td>
|
||||
<td>array</td>
|
||||
<td>是</td>
|
||||
<td>要写入的数据（字节数组）</td>
|
||||
</tr>
|
||||
</table>
|
||||
|
||||
<h4>请求示例</h4>
|
||||
<div class="example">
|
||||
[
|
||||
{
|
||||
"plc_name": "PLC1",
|
||||
"area_name": "DB100_Write",
|
||||
"offset": 0,
|
||||
"data": [1, 2, 3, 4]
|
||||
},
|
||||
{
|
||||
"plc_name": "PLC1",
|
||||
"area_name": "DB202_Params",
|
||||
"offset": 10,
|
||||
"data": [255, 0]
|
||||
}
|
||||
]
|
||||
</div>
|
||||
|
||||
<h4>响应示例</h4>
|
||||
<div class="example">
|
||||
[
|
||||
{
|
||||
"plc_name": "PLC1",
|
||||
"area_name": "DB100_Write",
|
||||
"status": "success",
|
||||
"plc_connection_status": "connected",
|
||||
"last_update": 1698754350.789,
|
||||
"last_update_formatted": "2023-10-30 14:12:30",
|
||||
"offset": 0,
|
||||
"length": 4
|
||||
},
|
||||
{
|
||||
"plc_name": "PLC1",
|
||||
"area_name": "DB202_Params",
|
||||
"status": "success",
|
||||
"plc_connection_status": "connected",
|
||||
"last_update": 1698754351.234,
|
||||
"last_update_formatted": "2023-10-30 14:12:31",
|
||||
"offset": 10,
|
||||
"length": 2
|
||||
}
|
||||
]
|
||||
</div>
|
||||
</div>
|
||||
|
||||
<div class="endpoint">
|
||||
<h3>Parsed Data</h3>
|
||||
<div>
|
||||
<span class="method method-get">GET</span>
|
||||
<code>/api/data/<plc_name>/<area_name></code>
|
||||
</div>
|
||||
<p>获取解析后的数据（如果配置了结构）。</p>
|
||||
|
||||
<h4>路径参数</h4>
|
||||
<table>
|
||||
<tr>
|
||||
<th>参数</th>
|
||||
<th>描述</th>
|
||||
</tr>
|
||||
<tr>
|
||||
<td>plc_name</td>
|
||||
<td>PLC名称（如PLC1）</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td>area_name</td>
|
||||
<td>区域名称（如DB100_Read）</td>
|
||||
</tr>
|
||||
</table>
|
||||
|
||||
<h4>响应示例（配置了解析结构）</h4>
|
||||
<div class="example">
|
||||
{
|
||||
"parsed": {
|
||||
"temperature": 25.5,
|
||||
"pressure": 100,
|
||||
"status": true
|
||||
},
|
||||
"raw_data": [0, 0, 128, 65, 0, 100],
|
||||
"status": "connected",
|
||||
"plc_connection_status": "connected",
|
||||
"last_update": 1698754321.456,
|
||||
"last_update_formatted": "2023-10-30 14:12:01"
|
||||
}
|
||||
</div>
|
||||
|
||||
<h4>响应示例（未配置解析结构）</h4>
|
||||
<div class="example">
|
||||
{
|
||||
"raw_data": [0, 0, 128, 65, 0, 100],
|
||||
"status": "connected",
|
||||
"plc_connection_status": "connected",
|
||||
"last_update": 1698754321.456,
|
||||
"last_update_formatted": "2023-10-30 14:12:01"
|
||||
}
|
||||
</div>
|
||||
</div>
|
||||
|
||||
<h2 id="config-api">Configuration API</h2>
|
||||
|
||||
<div class="endpoint">
|
||||
<h3>Get Configuration</h3>
|
||||
<div>
|
||||
<span class="method method-get">GET</span>
|
||||
<code>/api/config</code>
|
||||
</div>
|
||||
<p>获取当前配置。</p>
|
||||
|
||||
<h4>认证要求</h4>
|
||||
<p>需要Basic Auth认证</p>
|
||||
|
||||
<h4>响应示例</h4>
|
||||
<div class="example">
|
||||
{
|
||||
"plcs": [
|
||||
{
|
||||
"name": "PLC1",
|
||||
"ip": "192.168.0.10",
|
||||
"rack": 0,
|
||||
"slot": 1,
|
||||
"areas": [
|
||||
{
|
||||
"name": "DB100_Read",
|
||||
"type": "read",
|
||||
"db_number": 100,
|
||||
"offset": 0,
|
||||
"size": 4000,
|
||||
"structure": [
|
||||
{"name": "temperature", "type": "real", "offset": 0},
|
||||
{"name": "pressure", "type": "int", "offset": 4}
|
||||
]
|
||||
}
|
||||
]
|
||||
}
|
||||
]
|
||||
}
|
||||
</div>
|
||||
</div>
|
||||
|
||||
<div class="endpoint">
|
||||
<h3>Validate Configuration</h3>
|
||||
<div>
|
||||
<span class="method method-post">POST</span>
|
||||
<code>/api/config/validate</code>
|
||||
</div>
|
||||
<p>验证配置是否有效。</p>
|
||||
|
||||
<h4>认证要求</h4>
|
||||
<p>需要Basic Auth认证</p>
|
||||
|
||||
<h4>请求体</h4>
|
||||
<p>要验证的配置JSON</p>
|
||||
|
||||
<h4>响应示例（有效）</h4>
|
||||
<div class="example">
|
||||
{
|
||||
"valid": true
|
||||
}
|
||||
</div>
|
||||
|
||||
<h4>响应示例（无效）</h4>
|
||||
<div class="example">
|
||||
{
|
||||
"valid": false,
|
||||
"message": "Invalid configuration: 'ip' is a required property"
|
||||
}
|
||||
</div>
|
||||
</div>
|
||||
|
||||
<div class="endpoint">
|
||||
<h3>Save Configuration</h3>
|
||||
<div>
|
||||
<span class="method method-post">POST</span>
|
||||
<code>/api/config</code>
|
||||
</div>
|
||||
<p>保存配置。</p>
|
||||
|
||||
<h4>查询参数</h4>
|
||||
<table>
|
||||
<tr>
|
||||
<th>参数</th>
|
||||
<th>描述</th>
|
||||
</tr>
|
||||
<tr>
|
||||
<td>reload</td>
|
||||
<td>是否立即重载配置（true/false）</td>
|
||||
</tr>
|
||||
</table>
|
||||
|
||||
<h4>认证要求</h4>
|
||||
<p>需要Basic Auth认证</p>
|
||||
|
||||
<h4>请求体</h4>
|
||||
<p>要保存的配置JSON</p>
|
||||
|
||||
<h4>响应示例</h4>
|
||||
<div class="example">
|
||||
{
|
||||
"success": true,
|
||||
"message": "Configuration saved and reload requested"
|
||||
}
|
||||
</div>
|
||||
</div>
|
||||
|
||||
<div class="footer" style="margin-top: 40px; padding-top: 10px; border-top: 1px solid #ddd; color: #777;">
|
||||
<p>PLC Gateway v1.0 | <a href="/">Back to Status Page</a></p>
|
||||
</div>
|
||||
</body>
|
||||
</html>
|
||||
Reference in New Issue
Block a user