init：代码初始化
This commit is contained in:
bai
228
docs/API_DOCUMENTATION.md
Normal file
228
docs/API_DOCUMENTATION.md
Normal file
@@ -0,0 +1,228 @@
|
||||
# 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)
|
||||
Reference in New Issue
Block a user