OpenAPI 集成

概述

BPMAX 支持 OpenAPI 3.0 规范，可以快速导入和导出接口定义。使用 OpenAPI 的优势：

快速导入：从 OpenAPI 文档批量导入接口定义
标准化：使用业界标准的接口描述格式
易于共享：与其他系统和工具共享接口定义
文档生成：自动生成接口文档
工具支持：可以使用 Postman、Swagger UI 等工具

OpenAPI 3.0 简介

OpenAPI 规范（原 Swagger 规范）是一种用于描述 RESTful API 的标准格式。

基本结构

{
  "openapi": "3.0.0",
  "info": {
    "title": "示例接口 API",
    "version": "1.0.0",
    "description": "这是一个简短的 OpenAPI 3.0 接口示例。"
  },
  "paths": {
    "/users": {
      "get": {
        "summary": "获取用户列表",
        "description": "返回系统中的所有用户。",
        "responses": {
          "200": {
            "description": "成功返回用户列表",
            "content": {
              "application/json": {
                "schema": {
                  "type": "array",
                  "items": {
                    "type": "object",
                    "properties": {
                      "id": { "type": "integer", "example": 1 },
                      "name": { "type": "string", "example": "张三" },
                      "email": { "type": "string", "example": "zhangsan@example.com" }
                    }
                  }
                }
              }
            }
          }
        }
      }
    }
  }
}

导入 OpenAPI 文档

操作步骤

进入系统管理后台
导航至 集成管理 > 现在平台 > API管理
点击"导入 OpenAPI"按钮
选择导入方式
预览导入内容
确认导入

导入方式

1. 上传文件

支持上传 JSON 格式的 OpenAPI 文档。

操作步骤：

点击"上传文件"
选择本地的 OpenAPI 文件
系统自动解析文件内容
预览导入内容
点击"确认导入"

支持的文件格式：

JSON 格式：.json

2. 粘贴内容

直接粘贴 OpenAPI 文档内容。

操作步骤：

点击"粘贴内容"
在文本框中粘贴 OpenAPI 文档内容
选择格式（JSON）
点击"解析配置"
预览导入内容
点击"确认导入"

导入配置

预览导入内容

在确认导入前，系统会显示将要创建的内容：

1. 接口列表

显示所有将要导入的接口：

接口名称	请求方式	路径	描述
获取客户列表	GET	/api/customers	查询客户列表
创建客户	POST	/api/customers	创建新客户
获取客户详情	GET	/api/customers/{id}	查询客户详情

导入结果

导入完成后，系统会显示导入结果：

成功创建的接口平台
成功导入的接口数量
失败的接口及原因
生成响应实体（如果启用）

导入后的处理

导入完成后，您需要：

创建接口实例
- 配置基础 URL
- 配置鉴权信息
- 配置默认参数
测试接口
- 使用测试调用功能验证接口
- 检查参数映射是否正确
- 检查响应数据是否符合预期
完善文档
- 补充接口说明
- 添加使用示例
- 记录注意事项

导出 OpenAPI 文档

操作步骤

在接口平台详情页，点击"导出 OpenAPI"按钮
选择导出范围
配置导出选项
点击导出按钮，下载导出文件

导出格式

1. JSON 格式

导出为 JSON 格式的 OpenAPI 文档。

文件名：

{平台标识}_openapi.json

示例：

{
  "openapi": "3.0.0",
  "info": {
    "title": "CRM 系统 API",
    "version": "1.0.0",
    "description": "客户关系管理系统接口"
  },
  "servers": [
    {
      "url": "https://api.example.com",
      "description": "生产环境"
    }
  ],
  "paths": {
    "/api/customers": {
      "get": {
        "summary": "获取客户列表",
        "operationId": "getCustomerList",
        "parameters": [
          {
            "name": "page",
            "in": "query",
            "schema": {
              "type": "integer"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "成功",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/CustomerListResponse"
                }
              }
            }
          }
        }
      }
    }
  },
  "components": {
    "schemas": {
      "CustomerListResponse": {
        "type": "object",
        "properties": {
          "code": {
            "type": "integer"
          },
          "data": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/Customer"
            }
          }
        }
      },
      "Customer": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string"
          },
          "name": {
            "type": "string"
          }
        }
      }
    }
  }
}

导出范围

1. 导出所有接口

导出接口平台下的所有接口定义。

2. 导出选中的接口

只导出选中的接口定义。

操作步骤：

在接口列表中勾选要导出的接口
点击"导出 OpenAPI"
选择"导出选中的接口"
下载导出文件

导出用途

1. 与其他系统共享

将导出的 OpenAPI 文档分享给其他系统，方便他们了解和调用您的接口。

2. 生成接口文档

使用 Swagger UI、Redoc 等工具生成可视化的接口文档。

Swagger UI 示例：

<!DOCTYPE html>
<html>
<head>
  <link rel="stylesheet" href="https://unpkg.com/swagger-ui-dist/swagger-ui.css">
</head>
<body>
  <div id="swagger-ui"></div>
  <script src="https://unpkg.com/swagger-ui-dist/swagger-ui-bundle.js"></script>
  <script>
    SwaggerUIBundle({
      url: 'openapi.json',
      dom_id: '#swagger-ui'
    });
  </script>
</body>
</html>

3. 使用 Postman 测试

将导出的 OpenAPI 文档导入到 Postman 中进行测试。

操作步骤：

打开 Postman
点击 Import
选择导出的 OpenAPI 文件
Postman 会自动创建对应的请求集合

4. 版本控制

将 OpenAPI 文档纳入版本控制系统（如 Git），跟踪接口的变更历史。

5. 代码生成

使用 OpenAPI Generator 等工具，根据 OpenAPI 文档生成客户端代码。

示例：

# 生成 JavaScript 客户端
openapi-generator-cli generate -i openapi.json -g javascript -o ./client

# 生成 Java 客户端
openapi-generator-cli generate -i openapi.json -g java -o ./client

最佳实践

1. 保持文档更新

接口变更时及时更新 OpenAPI 文档
使用版本号管理文档
记录变更历史

2. 完善描述信息

为每个接口添加详细的描述
说明参数的含义和格式
提供请求和响应示例

3. 版本管理

在 URL 中包含版本号：/v1/api/...
在 info.version 中记录版本号
保持向后兼容

常见问题

Q1: 导入失败怎么办？

A: 检查以下几点：

OpenAPI 文档格式是否正确
是否符合 OpenAPI 3.0 规范
文件编码是否为 UTF-8
查看错误提示信息

Q2: 导入后接口无法调用？

检查是否创建了接口实例
检查实例的基础 URL 是否正确
检查鉴权配置是否正确
使用测试调用功能验证

Q3: 导出的文档如何使用？

导入到 Postman 进行测试
使用 Swagger UI 生成文档
使用 OpenAPI Generator 生成代码
与其他系统共享