guest/steel_prices_service

Fork 0

Files

bai ba478d70cc init：代码初始化

2026-01-06 09:19:12 +08:00

6.5 KiB

Raw Blame History

Swagger API 文档实施总结

✅ 完成的工作

1. 安装依赖

npm install swagger-jsdoc swagger-ui-express

2. 创建配置文件

文件: src/config/swagger.js

内容包括:

OpenAPI 3.0 规范配置
API 基本信息（标题、版本、描述）
服务器配置（开发/生产）
数据模型定义（Price、PriceStats、TrendData 等）
参数定义（复用参数模板）
响应模式定义

3. 添加 API 注解

文件: src/routes/api.js

已注解的接口:

✅ GET /api/health - 健康检查
✅ GET /api/prices/region - 按地区查询价格
✅ GET /api/prices/search - 搜索价格数据
✅ GET /api/prices/stats - 价格统计
✅ GET /api/prices/trend - 价格趋势
✅ POST /api/prices/import - 数据导入

注解内容包括:

详细的接口描述
参数说明（类型、必填、示例）
请求示例（多个场景）
响应 Schema（成功/失败）
错误码说明

4. 集成 Swagger UI

文件: src/app.js

配置功能:

✅ Swagger UI 中间件
✅ API 別览器（Explorer）
✅ 直接测试功能（Try it out）
✅ 请求耗时显示
✅ 请求头显示
✅ 自定义样式

5. 添加文档路由

文件: src/routes/index.js

新增路由:

GET /api-docs - Swagger UI 界面
GET /api-docs.json - JSON 格式的 OpenAPI 规范
GET / - API 信息和链接汇总

6. 创建文档

文档文件:

✅ docs/API_DOCUMENTATION.md - API 文档使用指南
✅ 更新 README.md - 添加 Swagger 说明

📊 API 文档统计

项目	数量
API 端点	6 个
数据模型	6 个
参数定义	6 个
API 分类	3 个
示例代码	10+ 个

🎯 数据模型清单

1. Price（价格数据）

{
  id: 1,
  region: "昆明",
  city: "昆明",
  material: "HPB300",
  specification: "Φ8",
  price: 3840.00,
  unit: "元/吨",
  date: "2026-01-05",
  source: "云南钢协",
  warehouse: "玉昆",
  created_at: "2026-01-05T10:00:00Z",
  updated_at: "2026-01-05T10:00:00Z"
}

2. PriceStats（价格统计）

{
  count: 150,
  avgPrice: 3950.50,
  minPrice: 3500.00,
  maxPrice: 4500.00,
  stdDev: 250.30,
  trend: "up",
  changeRate: "+2.5%"
}

3. TrendData（趋势数据）

{
  date: "2026-01-05",
  avgPrice: 3950.50,
  minPrice: 3800.00,
  maxPrice: 4100.00
}

4. Pagination（分页信息）

{
  page: 1,
  pageSize: 20,
  total: 100,
  totalPages: 5
}

5. SuccessResponse（成功响应）

{
  success: true,
  data: { ... }
}

6. ErrorResponse（错误响应）

{
  success: false,
  message: "参数验证失败",
  statusCode: 400
}

📖 使用方式

访问文档

启动服务
```
npm start
```
打开浏览器
```
http://localhost:3000/api-docs
```
测试 API
- 展开 API 端点
- 点击 "Try it out"
- 填写参数
- 点击 "Execute"
- 查看响应

导出规范

# 获取 JSON 格式的 OpenAPI 规范
curl http://localhost:3000/api-docs.json > openapi.json

🎨 Swagger UI 特性

已启用的功能

✅ Explorer - API 列表导航
✅ Try It Out - 直接测试 API
✅ Request Duration - 显示请求耗时
✅ Filter - 搜索和过滤 API
✅ Request Headers - 显示请求头
✅ Doc Expansion - 列表展开模式
✅ Models - 数据模型展示
✅ Examples - 请求/响应示例

自定义配置

{
  explorer: true,                          // 启用 API 导航
  customCss: '.swagger-ui .topbar { display: none }',  // 隐藏顶部栏
  customSiteTitle: 'Steel Prices Service API Documentation',  // 页面标题
  swaggerOptions: {
    persistAuthorization: true,            // 持久化认证
    displayRequestDuration: true,          // 显示请求耗时
    docExpansion: 'list',                  // 列表展开模式
    filter: true,                          // 启用过滤
    showRequestHeaders: true,              // 显示请求头
    tryItOutEnabled: true                  // 启用测试功能
  }
}

📝 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

🔍 参数说明

路径参数

无（本项目使用查询参数）

查询参数

参数	类型	必填	说明	示例
region	string	是	地区	昆明
material	string	否	材质	HPB300
specification	string	否	规格型号	Φ8
date	date	否	日期	2026-01-05
startDate	date	否	开始日期	2026-01-01
endDate	date	否	结束日期	2026-01-05
days	integer	否	天数	30
page	integer	否	页码	1
pageSize	integer	否	每页数量	20

💡 高级功能

1. 参数复用

使用 $ref 引用预定义的参数：

parameters:
  - $ref: '#/components/parameters/RegionParam'
  - $ref: '#/components/parameters/DateParam'

2. 数据模型复用

使用 $ref 引用预定义的模型：

schema:
  $ref: '#/components/schemas/Price'

3. 多示例支持

为同一个接口提供多个使用示例：

examples:
  search_by_material:
    summary: 按材质搜索
    value: { material: "HPB300" }
  search_by_date_range:
    summary: 按日期范围搜索
    value: { startDate: "2026-01-01", endDate: "2026-01-05" }

📚 相关文档

🎉 总结

✅ Swagger 文档系统已完全集成！

主要特性:

6 个完整的 API 端点文档
6 个详细的数据模型定义
10+ 个使用示例
交互式测试功能
美观的用户界面
完整的参数说明

访问地址:

Swagger UI: http://localhost:3000/api-docs
JSON 规范: http://localhost:3000/api-docs.json

下一步: 启动服务并访问 Swagger UI 开始探索 API！

6.5 KiB Raw Blame History Unescape Escape