# node-red-contrib-dfswagger

**Repository Path**: dfskgh/node-red-contrib-dfswagger

## Basic Information

- **Project Name**: node-red-contrib-dfswagger
- **Description**: 东方数科 Swagger API 集成节点，自动从 OpenAPI 规范生成 Node-RED API 调用节点。
- **Primary Language**: Unknown
- **License**: Apache-2.0
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 4
- **Forks**: 0
- **Created**: 2025-12-11
- **Last Updated**: 2026-02-23

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# node-red-contrib-dfswagger

> 东方数科 Swagger API 集成节点，自动从 OpenAPI 规范生成 Node-RED API 调用节点。

## 功能特性

DFSwagger 节点能够自动解析 Swagger/OpenAPI 规范，并生成对应的 API 调用节点，提供以下核心功能：

- **自动节点生成**：从 Swagger 文档自动创建 Node-RED 节点[1](@ref)
- **多格式支持**：兼容 Swagger 2.0 和 OpenAPI 3.0/3.1 规范[4](@ref)
- **身份认证集成**：支持 API Key、OAuth2、JWT 等认证方式
- **请求验证**：自动验证请求参数和数据结构
- **文档同步**：API 文档更新时自动同步节点定义

## 安装方法

### 前提条件
- Node.js 版本 14.0 或更高版本
- Node-RED 版本 1.0 或更高版本
- Swagger/OpenAPI 文档（本地文件或可访问的 URL）

### 安装步骤
bash
通过 npm 安装
npm install node-red-contrib-dfswagger
安装 Node-RED NodeGen 工具（可选，用于高级功能）
npm install -g node-red-nodegen
1
## 快速开始

### 基础配置
1. 拖动 `dfswagger-importer` 节点到工作区
2. 配置 Swagger 文档路径（本地文件或 URL）
3. 设置生成的节点分类和前缀
4. 部署后自动生成对应的 API 节点

### 从 Swagger 文档生成节点
bash
使用 node-red-nodegen 从 Swagger 文档生成节点
1
node-red-nodegen ./api-spec.yaml --name df-api-client --category "东方数科API"
## 使用示例

### API 客户端配置
json
[
{
"id": "swagger-importer",
"type": "dfswagger-importer",
"name": "用户服务API",
"specUrl": "https://api.example.com/swagger.json",
"category": "user-service",
"authType": "apiKey",
"wires": [["api-generator"]]
}
]
### 生成的 API 调用节点
json
[
{
"id": "user-create",
"type": "dfswagger-user-create",
"name": "创建用户",
"endpoint": "/users",
"method": "POST",
"parameters": {
"body": {"name": "", "email": ""}
},
"wires": [["response-handler"]]
}
]
## 核心功能

### OpenAPI 规范支持
支持完整的 OpenAPI 规范元素[4](@ref)：
- **路径操作**：GET、POST、PUT、DELETE 等 HTTP 方法
- **参数处理**：路径参数、查询参数、请求体参数
- **响应解析**：自动解析 JSON、XML 等响应格式
- **错误处理**：HTTP 状态码映射和错误信息提取

### 认证配置
支持多种认证机制：
javascript
// API Key 认证
auth: {
type: "apiKey",
key: "X-API-Key",
value: "your-api-key-here",
in: "header"
}
// OAuth2 认证
auth: {
type: "oauth2",
flow: "password",
tokenUrl: "https://api.example.com/oauth/token",
clientId: "your-client-id",
clientSecret: "your-client-secret"
}
## 高级功能

### 批量 API 生成
支持批量生成多个 API 端点：
javascript
batchGenerate: {
enabled: true,
include: ["/users/", "/orders/"],
exclude: ["/admin/*"],
concurrency: 5
}
### 文档同步监控
监控 Swagger 文档变化并自动更新：
javascript
watchOptions: {
enabled: true,
interval: 300000, // 5分钟检查一次
autoUpdate: true
}
## 最佳实践

### API 设计建议
1. **规范的 Swagger 文档**：确保 Swagger 文档完整且符合 OpenAPI 规范[5](@ref)
2. **明确的参数说明**：为每个参数提供详细的描述和示例
3. **一致的错误格式**：使用统一的错误响应格式
4. **版本管理**：为 API 提供版本控制支持

### 性能优化
- 使用本地缓存减少 Swagger 文档解析时间
- 启用连接池管理 HTTP 连接
- 配置合理的请求超时时间

## 故障排除

### 常见问题
1. **Swagger 文档解析失败**：检查文档是否符合 OpenAPI 规范[4](@ref)
2. **认证错误**：验证认证配置参数是否正确
3. **节点生成失败**：确认 Swagger 文档路径可访问

### 调试模式
启用详细日志记录：
javascript
// 在节点配置中启用调试
{
"debug": true,
"logLevel": "verbose"
}
## 相关资源
- [OpenAPI 规范文档](https://swagger.io/specification/)
- [Swagger 编辑器](https://editor.swagger.io/)
- [东方数科 API 设计指南](https://docs.east-digital.com/api-design)

## 许可证
Apache-2.0 License © 2025 东方数科