229 lines
5.0 KiB
Markdown
229 lines
5.0 KiB
Markdown
# API 文档说明
|
||
|
||
## 📚 Swagger 文档已集成
|
||
|
||
Steel Prices Service 现已集成完整的 Swagger API 文档系统！
|
||
|
||
### 访问方式
|
||
|
||
启动服务后，可以通过以下方式访问 API 文档：
|
||
|
||
#### 1. Swagger UI 界面（推荐）
|
||
|
||
```
|
||
http://localhost:3000/api-docs
|
||
```
|
||
|
||
**特点：**
|
||
- 📖 交互式 API 文档
|
||
- 🧪 可直接在浏览器中测试 API
|
||
- 📝 完整的请求/响应示例
|
||
- 🔍 参数说明和验证规则
|
||
- 🎨 美观的用户界面
|
||
|
||
#### 2. JSON 格式的 OpenAPI 规范
|
||
|
||
```
|
||
http://localhost:3000/api-docs.json
|
||
```
|
||
|
||
用于：
|
||
- 导入到其他 API 工具（Postman、Insomnia）
|
||
- 自动生成客户端 SDK
|
||
- API 版本管理
|
||
|
||
#### 3. API 信息接口
|
||
|
||
```
|
||
http://localhost:3000/
|
||
```
|
||
|
||
返回所有可用的 API 端点和文档链接。
|
||
|
||
---
|
||
|
||
## 📖 文档内容
|
||
|
||
### API 端点分类
|
||
|
||
#### Health（健康检查）
|
||
- `GET /api/health` - 检查服务状态
|
||
|
||
#### Prices（价格查询）
|
||
- `GET /api/prices/region` - 按地区查询价格
|
||
- `GET /api/prices/search` - 多条件搜索价格
|
||
- `GET /api/prices/stats` - 价格统计分析
|
||
- `GET /api/prices/trend` - 价格趋势分析
|
||
|
||
#### Data（数据管理）
|
||
- `POST /api/prices/import` - 批量导入价格数据
|
||
|
||
### 数据模型
|
||
|
||
#### Price（价格数据）
|
||
- region - 地区（必填）
|
||
- city - 城市
|
||
- material - 材质（必填）
|
||
- specification - 规格型号
|
||
- price - 价格（必填）
|
||
- unit - 单位
|
||
- date - 日期（必填）
|
||
- source - 数据来源
|
||
- warehouse - 仓库/厂家
|
||
|
||
#### PriceStats（价格统计）
|
||
- count - 记录数量
|
||
- avgPrice - 平均价格
|
||
- minPrice - 最低价格
|
||
- maxPrice - 最高价格
|
||
- stdDev - 标准差
|
||
- trend - 价格趋势
|
||
- changeRate - 变化率
|
||
|
||
---
|
||
|
||
## 🧪 如何使用 Swagger UI
|
||
|
||
### 1. 浏览 API
|
||
|
||
1. 打开 `http://localhost:3000/api-docs`
|
||
2. 展开左侧的 API 分类标签
|
||
3. 点击感兴趣的 API 端点
|
||
|
||
### 2. 测试 API
|
||
|
||
1. 在 API 详情页点击 "Try it out" 按钮
|
||
2. 填写必填参数（标红的字段）
|
||
3. 点击 "Execute" 执行请求
|
||
4. 查看响应结果
|
||
|
||
### 3. 查看数据模型
|
||
|
||
1. 滚动到页面底部的 "Schemas" 部分
|
||
2. 点击模型名称查看详细字段说明
|
||
3. 查看示例数据格式
|
||
|
||
---
|
||
|
||
## 📝 示例：测试 API
|
||
|
||
### 示例 1：按地区查询价格
|
||
|
||
**请求：**
|
||
```
|
||
GET /api/prices/region?region=昆明&date=2026-01-05
|
||
```
|
||
|
||
**在 Swagger UI 中的步骤：**
|
||
1. 展开 `GET /api/prices/region`
|
||
2. 点击 "Try it out"
|
||
3. 在 region 字段输入：`昆明`
|
||
4. 在 date 字段输入：`2026-01-05`（可选）
|
||
5. 点击 "Execute"
|
||
6. 查看响应结果
|
||
|
||
### 示例 2：搜索价格数据
|
||
|
||
**请求：**
|
||
```
|
||
GET /api/prices/search?material=HPB300&page=1&pageSize=20
|
||
```
|
||
|
||
**在 Swagger UI 中的步骤：**
|
||
1. 展开 `GET /api/prices/search`
|
||
2. 点击 "Try it out"
|
||
3. 在 material 字段输入：`HPB300`
|
||
4. 在 page 字段输入：`1`
|
||
5. 在 pageSize 字段输入：`20`
|
||
6. 点击 "Execute"
|
||
7. 查看响应结果和分页信息
|
||
|
||
### 示例 3：获取价格统计
|
||
|
||
**请求：**
|
||
```
|
||
GET /api/prices/stats?region=昆明&material=HPB300&days=30
|
||
```
|
||
|
||
**在 Swagger UI 中的步骤：**
|
||
1. 展开 `GET /api/prices/stats`
|
||
2. 点击 "Try it out"
|
||
3. 在 region 字段输入：`昆明`
|
||
4. 在 material 字段输入：`HPB300`
|
||
5. 在 days 字段输入：`30`
|
||
6. 点击 "Execute"
|
||
7. 查看统计数据
|
||
|
||
---
|
||
|
||
## 🔧 Swagger UI 配置
|
||
|
||
### 启用的功能
|
||
|
||
- ✅ **Explorer** - API 列表导航
|
||
- ✅ **Try It Out** - 直接测试 API
|
||
- ✅ **Request Duration** - 显示请求耗时
|
||
- ✅ **Filter** - 搜索和过滤 API
|
||
- ✅ **Request Headers** - 显示请求头
|
||
- ✅ **Doc Expansion** - 列表展开方式
|
||
|
||
### 自定义配置
|
||
|
||
位置：[src/app.js](../src/app.js)
|
||
|
||
```javascript
|
||
app.use('/api-docs', swaggerUi.serve, swaggerUi.setup(swaggerSpec, {
|
||
explorer: true, // 启用 API 导航
|
||
customCss: '.swagger-ui .topbar { display: none }', // 自定义 CSS
|
||
customSiteTitle: 'Steel Prices Service API Documentation', // 页面标题
|
||
swaggerOptions: {
|
||
persistAuthorization: true, // 持久化认证
|
||
displayRequestDuration: true, // 显示请求耗时
|
||
docExpansion: 'list', // 列表展开模式
|
||
filter: true, // 启用过滤
|
||
showRequestHeaders: true, // 显示请求头
|
||
tryItOutEnabled: true // 启用测试功能
|
||
}
|
||
}));
|
||
```
|
||
|
||
---
|
||
|
||
## 📚 相关文档
|
||
|
||
- [src/config/swagger.js](../src/config/swagger.js) - Swagger 配置文件
|
||
- [src/routes/api.js](../src/routes/api.js) - API 路由和注解
|
||
- [OpenAPI 3.0 规范](https://swagger.io/specification/) - 官方规范
|
||
|
||
---
|
||
|
||
## 🎯 快速开始
|
||
|
||
1. **启动服务**
|
||
```bash
|
||
npm start
|
||
```
|
||
|
||
2. **打开浏览器**
|
||
```
|
||
http://localhost:3000/api-docs
|
||
```
|
||
|
||
3. **开始测试 API**
|
||
- 选择一个 API 端点
|
||
- 点击 "Try it out"
|
||
- 填写参数并执行
|
||
|
||
---
|
||
|
||
## 💡 提示
|
||
|
||
- 所有参数都有详细的说明和示例
|
||
- 必填参数会用红色标记
|
||
- 响应数据包含完整的 JSON Schema
|
||
- 可以直接复制示例代码使用
|
||
|
||
---
|
||
|
||
**有问题？** 查看 [README.md](../README.md) 或 [快速开始指南](QUICK_START.md)
|