OpenAPI 集成示例

基于 Spring Boot 的 OpenAPI 集成示例项目，演示如何通过文档中台的 PublicAPI 实现格式转换、文档水印、文档套红等 OpenAPI 功能。

集成方案详细介绍

如果您需要查看完整的 OpenAPI 文档，请访问 Open API 手册。

如何获取示例代码

github 仓库 OpenAPI 集成在 openapi-solution/java/filez-demo 目录

重要提示

本项目仅用于测试和演示目的。请勿在生产服务器上直接使用，必须进行适当的代码修改和安全加固！

技术栈

框架: Spring Boot 2.5.4
数据库: SQLite (内嵌数据库，无需额外安装)
ORM: MyBatis Plus 3.4.3.4
模板引擎: FreeMarker
API文档: Knife4j (Swagger)
JSON处理: Fastjson 1.2.83
HTTP客户端: Apache HttpClient 4.5.13
认证: HMAC-SHA256 签名认证

前置要求

Java: JDK 8 或更高版本
Maven: 3.6 或更高版本
文档中台: 已部署 luoshu-server 且开启 PublicAPI

功能清单与对应 Controller

功能	Controller	路径	说明
格式转换	`ConvertController.java`	`/home/convert`	Word/Excel/PPT → PDF/OFD
添加水印	`WatermarkController.java`	`/home/watermark`	文本/图片/平铺水印
文档套红	`BookmarkController.java`	`/home/bookmark`	书签内容替换（TEXT/PIC/DOC）
图片转 PDF	`Img2PdfController.java`	`/home/imageToPdf`	多张图片合成 PDF
JSON 转 Excel	`Json2ExcelController.java`	`/home/jsonToExcel`	JSON 数据导出 Excel
文档拆分	`DocSplitController.java`	`/home/docSplit`	PDF/Word 按页拆分
任务池	`TaskPoolController.java`	`/home/tasks`	查看所有任务状态

项目结构

openapi-solution/java/filez-demo/
├── src/main/java/com/filez/demo/
│   ├── controller/
│   │   ├── ConvertController.java        # 格式转换 ⭐
│   │   ├── WatermarkController.java      # 水印操作 ⭐
│   │   ├── BookmarkController.java       # 文档套红 ⭐
│   │   ├── Img2PdfController.java        # 图片转PDF ⭐
│   │   ├── Json2ExcelController.java     # JSON转Excel ⭐
│   │   ├── DocSplitController.java       # 文档拆分 ⭐
│   │   ├── TaskPoolController.java       # 任务池
│   │   ├── FileController.java           # 文件管理
│   │   ├── ZOfficeController.java        # 基础集成回调
│   │   └── LoginController.java          # 登录认证
│   ├── service/
│   │   ├── OpenApiTaskService.java       # OpenAPI 任务接口 ⭐
│   │   └── impl/
│   │       └── OpenApiTaskServiceImpl.java  # HMAC签名+调用实现 ⭐
│   ├── config/
│   │   ├── PublicApiConfig.java          # PublicAPI 配置 ⭐
│   │   └── DemoConfig.java              # 业务系统配置
│   └── common/utils/
│       ├── PublicApiAuthUtil.java         # HMAC 签名工具 ⭐
│       └── HmacUtil.java                 # SHA256 加密
├── src/main/resources/
│   ├── application.yml
│   ├── zoffice.yml                       # 连接配置 ⭐
│   ├── internal-local-file/              # 内置测试文件
│   └── templates/                        # 前端页面模板
└── local-file/                           # 运行时文件存储

实现方式说明

核心调用流程

所有 OpenAPI 功能采用异步任务模式，流程如下：

前端选择文件 → 提交任务参数
Controller 调用 OpenApiTaskServiceImpl
ServiceImpl 构建请求体 + HMAC 签名 → 调用文档中台 PublicAPI
文档中台返回 taskId → 前端每 2 秒轮询任务状态
任务完成后：前端获取结果 docId → 预览/下载结果文件

任务状态查询

前端通过 /home/tasks/taskStatus?taskId=xxx 主动轮询，后端调用文档中台的任务状态查询接口获取最新状态。同时文档中台也会回调 callback 地址通知任务完成，回调结果会更新本地数据库中的任务记录。

HMAC 签名认证

所有对文档中台 PublicAPI 的请求需要 HMAC-SHA256 签名：

// PublicApiAuthUtil.java
public static void setAuthHeaders(HttpPost httpPost, String requestBody) {
    String timestamp = String.valueOf(System.currentTimeMillis() / 1000);
    String signature = HmacUtil.hmacSha256(appSecret, requestBody + timestamp);
    httpPost.setHeader("X-Auth-AppId", appId);
    httpPost.setHeader("X-Auth-Signature", signature);
    httpPost.setHeader("X-Auth-TimeStamp", timestamp);
}

请求体结构（以 content/update 为例）

格式转换使用 /convert 接口，水印和套红使用 /content/update 接口：

// OpenApiTaskServiceImpl.java - buildRequestBody
JSONObject body = new JSONObject();
body.put("filename", docName);          // 源文件名
body.put("fileUrl", buildFileUrl(docId)); // 文件下载 URL
body.put("callback", buildCallbackUrl()); // 回调通知地址
body.put("tokenType", "cookie");
body.put("tokenValue", tokenName + "=" + userToken);
body.put("ops", JSON.parseArray(opsJson)); // 操作数组

快速开始

1. 编译项目

git clone https://github.com/FilezOffice/documentserver-example.git
cd documentserver-example/openapi-solution/java/filez-demo

mvn clean package -DskipTests

2. 配置连接

编辑 src/main/resources/zoffice.yml：

zoffice:
  service:
    host: '<your-zoffice-host>'       # 文档中台服务 IP/域名
    port: 8001
    app:
      secret: 'default-salt'          # 需与管理控制台一致
    publicapi:
      app-id: 'publicApi'             # PublicAPI 应用ID
      secret: 'default-salt'          # PublicAPI 密钥
      context: '/publicapi/v1'

demo:
  host: '<your-demo-host>'            # 本机 IP（需保证文档中台可访问）
  context: '/v2/context'
  repoId: '3rd-party'                 # 与管理控制台应用设置一致

关键配置

zoffice.service.host 和 demo.host 必须是文档中台和本机之间互相可访问的地址
publicapi.secret 必须与管理控制台中配置的密钥一致
可通过环境变量覆盖（如 ZOFFICE_HOST、DEMO_HOST）

3. 启动应用

java -jar target/filez-demo-1.0.0.RELEASE.jar

或使用环境变量：

java -jar target/filez-demo-1.0.0.RELEASE.jar \
  --zoffice.service.host=192.168.1.100 \
  --demo.host=192.168.1.50

4. 访问应用

服务	地址	说明
主页	http://localhost:8000	应用主入口
API 文档	http://localhost:8000/doc.html	Swagger API 文档
格式转换	http://localhost:8000/home/convert	格式转换页
添加水印	http://localhost:8000/home/watermark	水印操作页
文档套红	http://localhost:8000/home/bookmark	书签替换页

默认账号: 用户名 admin，密码 zOffice

各功能使用说明

格式转换

支持 Word/Excel/PPT 转 PDF/OFD。选择源文件和目标格式后提交，可选附加水印。

接口: POST /publicapi/v1/convert
Controller: ConvertController.java

添加水印

支持对 Word/PDF/OFD 文件添加四种水印类型：

固定位置文本水印（ApplyWatermark）
固定位置图片水印（ApplyPicWatermark）
平铺文本水印（ApplyWatermarkForFixed）
平铺图片水印（ApplyTiledImgWatermarkForFixed）

PPT 文件会自动先转为 PDF 再添加水印。

接口: POST /publicapi/v1/content/update
Controller: WatermarkController.java

文档套红（书签内容替换）

对含书签的 Word 模板进行内容替换，支持三种引用类型：

TEXT: 替换为纯文本
PIC: 替换为图片（png/jpg）
DOC: 替换为子文档内容（doc/docx/wps）

项目内置 bookmark_template.docx 模板，包含 6 个预设书签可直接测试。

接口: POST /publicapi/v1/content/update（actId: UpdateBookmarkRef）
Controller: BookmarkController.java

文档拆分

支持 PDF 和 Word 按页范围、固定页数、关键字等方式拆分。

接口: POST /publicapi/v1/split
Controller: DocSplitController.java

停止服务

# Linux/macOS
ps aux | grep filez-demo
kill <PID>

# Windows
tasklist | findstr java
taskkill /PID <PID> /F

技术栈​

前置要求​

功能清单与对应 Controller​

项目结构​

实现方式说明​

核心调用流程​

HMAC 签名认证​

请求体结构（以 content/update 为例）​

快速开始​

1. 编译项目​

2. 配置连接​

3. 启动应用​

4. 访问应用​

各功能使用说明​

格式转换​

添加水印​

文档套红（书签内容替换）​

文档拆分​

停止服务​

参考资源​

技术栈