API 文档

IPAM 提供 RESTful API 接口，支持标准的 HTTP 方法和 JSON 数据格式。

API 概览

基础信息

项目	内容
基础 URL	http://localhost:8080/api
数据格式	JSON
认证方式	JWT Token
字符编码	UTF-8

请求格式

GET /api/ip-addresses HTTP/1.1
Host: localhost:8080
Authorization: Bearer <token>
Content-Type: application/json

响应格式

{
  "success": true,
  "data": {},
  "message": "操作成功"
}

标准响应码

状态码	说明
200	请求成功
201	创建成功
400	请求参数错误
401	未授权
403	禁止访问
404	资源不存在
500	服务器内部错误

认证

登录

POST /api/login
Content-Type: application/json

{
  "username": "admin",
  "password": "admin123"
}

响应：

{
  "success": true,
  "data": {
    "token": "eyJhbGciOiJIUzI1NiIs...",
    "expire": "2024-01-16T10:30:00Z",
    "user": {
      "id": 1,
      "username": "admin",
      "role": "admin"
    }
  }
}

使用 Token

在请求头中添加 Authorization：

Authorization: Bearer eyJhbGciOiJIUzI1NiIs...

分页查询

列表接口支持分页查询：

GET /api/ip-addresses?page=1&page_size=20

响应：

{
  "success": true,
  "data": {
    "list": [],
    "total": 100,
    "page": 1,
    "page_size": 20
  }
}

分页参数

参数	类型	默认值	说明
page	int	1	页码
page_size	int	20	每页数量

错误处理

错误响应格式

{
  "success": false,
  "error": {
    "code": "INVALID_PARAMETER",
    "message": "请求参数错误",
    "details": {
      "ip": "IP地址格式不正确"
    }
  }
}

错误码列表

错误码	说明
INVALID_PARAMETER	请求参数错误
UNAUTHORIZED	未授权
FORBIDDEN	禁止访问
NOT_FOUND	资源不存在
ALREADY_EXISTS	资源已存在
INTERNAL_ERROR	内部服务器错误

资源接口

IP 地址管理

方法	路径	说明
GET	/api/ip-addresses	获取 IP 列表
GET	/api/ip-addresses/:id	获取 IP 详情
POST	/api/ip-addresses	创建 IP
PUT	/api/ip-addresses/:id	更新 IP
DELETE	/api/ip-addresses/:id	删除 IP
PUT	/api/ip-addresses/:id/allocate	分配 IP
PUT	/api/ip-addresses/:id/release	释放 IP

子网管理

方法	路径	说明
GET	/api/subnets	获取子网列表
POST	/api/subnets	创建子网
PUT	/api/subnets/:id	更新子网
DELETE	/api/subnets/:id	删除子网

网关管理

方法	路径	说明
GET	/api/gateways	获取网关列表
POST	/api/gateways	创建网关
PUT	/api/gateways/:id	更新网关
DELETE	/api/gateways/:id	删除网关

网络区域管理

方法	路径	说明
GET	/api/network-areas	获取网络区域列表
POST	/api/network-areas	创建网络区域
PUT	/api/network-areas/:id	更新网络区域
DELETE	/api/network-areas/:id	删除网络区域

单位管理

方法	路径	说明
GET	/api/units	获取单位列表
POST	/api/units	创建单位
PUT	/api/units/:id	更新单位
DELETE	/api/units/:id	删除单位

部门管理

方法	路径	说明
GET	/api/departments	获取部门列表
POST	/api/departments	创建部门
PUT	/api/departments/:id	更新部门
DELETE	/api/departments/:id	删除部门

项目管理

方法	路径	说明
GET	/api/projects	获取项目列表
POST	/api/projects	创建项目
PUT	/api/projects/:id	更新项目
DELETE	/api/projects/:id	删除项目

用户管理

方法	路径	说明
GET	/api/users	获取用户列表
POST	/api/users	创建用户
PUT	/api/users/:id	更新用户
DELETE	/api/users/:id	删除用户
PUT	/api/users/:id/reset-password	重置密码

导入导出

方法	路径	说明
GET	/api/full-export	全量导出
POST	/api/full-import/preview	导入预览
POST	/api/full-import	执行导入
GET	/api/full-import/template	下载模板

监控接口

方法	路径	说明
GET	/api/monitoring/status	获取监控状态
GET	/api/monitoring/stats	获取监控统计
POST	/api/monitoring/scan	手动触发扫描

探针接口

方法	路径	说明
POST	/api/probe/report-mac-results	上报扫描结果
POST	/api/probe/validate-api-key	验证 API 密钥

示例代码

cURL

# 登录
curl -X POST http://localhost:8080/api/login \
  -H "Content-Type: application/json" \
  -d '{"username":"admin","password":"admin123"}'

# 获取 IP 列表
curl -X GET http://localhost:8080/api/ip-addresses \
  -H "Authorization: Bearer <token>"

# 创建子网
curl -X POST http://localhost:8080/api/subnets \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "办公网段",
    "cidr": "192.168.1.0/24",
    "gateway_id": 1,
    "network_area_id": 1
  }'

Python

import requests

# 登录
response = requests.post('http://localhost:8080/api/login', json={
    'username': 'admin',
    'password': 'admin123'
})
token = response.json()['data']['token']

# 获取 IP 列表
headers = {'Authorization': f'Bearer {token}'}
response = requests.get('http://localhost:8080/api/ip-addresses', headers=headers)
ip_list = response.json()['data']['list']

JavaScript

// 登录
const login = async () => {
  const response = await fetch('http://localhost:8080/api/login', {
    method: 'POST',
    headers: { 'Content-Type': 'application/json' },
    body: JSON.stringify({ username: 'admin', password: 'admin123' })
  });
  const data = await response.json();
  return data.data.token;
};

// 获取 IP 列表
const getIPAddresses = async (token) => {
  const response = await fetch('http://localhost:8080/api/ip-addresses', {
    headers: { 'Authorization': `Bearer ${token}` }
  });
  return await response.json();
};

Swagger 文档

系统提供 Swagger UI 接口文档：

http://localhost:8080/swagger/index.html

Swagger 文档包含所有接口的详细说明、请求参数和响应示例。