OpenAPI Integration Example

A Spring Boot-based OpenAPI integration example project demonstrating how to implement format conversion, document watermarking, bookmark content replacement and other OpenAPI features through the Document Platform's PublicAPI.

Integration Guide

For complete OpenAPI documentation, please visit Open API Manual.

How to Get the Source Code

GitHub Repository OpenAPI integration is located in the openapi-solution/java/filez-demo directory

Important Notice

This project is for testing and demonstration purposes only. Do NOT use it directly on production servers — proper code modifications and security hardening are required!

Tech Stack

• Framework: Spring Boot 2.5.4
• Database: SQLite (embedded, no installation required)
• ORM: MyBatis Plus 3.4.3.4
• Template Engine: FreeMarker
• API Docs: Knife4j (Swagger)
• JSON: Fastjson 1.2.83
• HTTP Client: Apache HttpClient 4.5.13
• Authentication: HMAC-SHA256 Signature

Prerequisites

• Java: JDK 8 or higher
• Maven: 3.6 or higher
• Document Platform: luoshu-server deployed with PublicAPI enabled

Feature List & Corresponding Controllers

Feature	Controller	Path	Description
Format Conversion	ConvertController.java	/home/convert	Word/Excel/PPT → PDF/OFD
Add Watermark	WatermarkController.java	/home/watermark	Text/Image/Tiled watermark
Bookmark Replacement	BookmarkController.java	/home/bookmark	Bookmark content replacement (TEXT/PIC/DOC)
Image to PDF	Img2PdfController.java	/home/imageToPdf	Merge multiple images into PDF
JSON to Excel	Json2ExcelController.java	/home/jsonToExcel	Export JSON data to Excel
Document Split	DocSplitController.java	/home/docSplit	Split PDF/Word by pages
Task Pool	TaskPoolController.java	/home/tasks	View all task statuses

Project Structure

openapi-solution/java/filez-demo/
├── src/main/java/com/filez/demo/
│   ├── controller/
│   │   ├── ConvertController.java        # Format conversion ⭐
│   │   ├── WatermarkController.java      # Watermark operations ⭐
│   │   ├── BookmarkController.java       # Bookmark replacement ⭐
│   │   ├── Img2PdfController.java        # Image to PDF ⭐
│   │   ├── Json2ExcelController.java     # JSON to Excel ⭐
│   │   ├── DocSplitController.java       # Document split ⭐
│   │   ├── TaskPoolController.java       # Task pool
│   │   ├── FileController.java           # File management
│   │   ├── ZOfficeController.java        # Basic integration callbacks
│   │   └── LoginController.java          # Login authentication
│   ├── service/
│   │   ├── OpenApiTaskService.java       # OpenAPI task interface ⭐
│   │   └── impl/
│   │       └── OpenApiTaskServiceImpl.java  # HMAC signing + invocation ⭐
│   ├── config/
│   │   ├── PublicApiConfig.java          # PublicAPI config ⭐
│   │   └── DemoConfig.java              # Business system config
│   └── common/utils/
│       ├── PublicApiAuthUtil.java         # HMAC signing utility ⭐
│       └── HmacUtil.java                 # SHA256 encryption
├── src/main/resources/
│   ├── application.yml
│   ├── zoffice.yml                       # Connection config ⭐
│   ├── internal-local-file/              # Built-in test files
│   └── templates/                        # Frontend page templates
└── local-file/                           # Runtime file storage

Implementation Details

Core Invocation Flow

All OpenAPI features use an asynchronous task model:

1. Frontend selects file → submits task parameters
2. Controller calls OpenApiTaskServiceImpl
3. ServiceImpl builds request body + HMAC signature → calls Document Platform PublicAPI
4. Document Platform returns taskId → frontend polls task status every 2 seconds
5. On completion: frontend retrieves result docId → preview/download result file

Task Status Query

The frontend actively polls via /home/tasks/taskStatus?taskId=xxx, and the backend calls the Document Platform's task status query API. Additionally, the Document Platform also sends a callback to the callback URL upon task completion, which updates the task record in the local database.

HMAC Signature Authentication

All requests to the Document Platform's PublicAPI require HMAC-SHA256 signatures:

// 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);
}

Request Body Structure (content/update example)

Format conversion uses the /convert API; watermark and bookmark operations use /content/update:

// OpenApiTaskServiceImpl.java - buildRequestBody
JSONObject body = new JSONObject();
body.put("filename", docName);          // Source filename
body.put("fileUrl", buildFileUrl(docId)); // File download URL
body.put("callback", buildCallbackUrl()); // Callback notification URL
body.put("tokenType", "cookie");
body.put("tokenValue", tokenName + "=" + userToken);
body.put("ops", JSON.parseArray(opsJson)); // Operations array

Quick Start

1. Build the Project

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

mvn clean package -DskipTests

2. Configure Connection

Edit src/main/resources/zoffice.yml:

zoffice:
  service:
    host: '<your-zoffice-host>'       # Document Platform server IP/domain
    port: 8001
    app:
      secret: 'default-salt'          # Must match admin console settings
    publicapi:
      app-id: 'publicApi'             # PublicAPI application ID
      secret: 'default-salt'          # PublicAPI secret key
      context: '/publicapi/v1'

demo:
  host: '<your-demo-host>'            # Local IP (must be accessible from Document Platform)
  context: '/v2/context'
  repoId: '3rd-party'                 # Must match admin console app settings

Key Configuration

• zoffice.service.host and demo.host must be mutually accessible between the Document Platform and the demo server
• publicapi.secret must match the secret configured in the admin console
• Can be overridden via environment variables (e.g., ZOFFICE_HOST, DEMO_HOST)

3. Start the Application

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

Or with environment variables:

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

4. Access the Application

Service	URL	Description
Home	http://localhost:8000	Application entry
API Docs	http://localhost:8000/doc.html	Swagger API docs
Format Conversion	http://localhost:8000/home/convert	Conversion page
Add Watermark	http://localhost:8000/home/watermark	Watermark page
Bookmark Replacement	http://localhost:8000/home/bookmark	Bookmark page

Default credentials: Username admin, Password zOffice

Feature Usage

Format Conversion

Supports Word/Excel/PPT to PDF/OFD. Select a source file and target format, optionally with watermark.

• API: POST /publicapi/v1/convert
• Controller: ConvertController.java

Add Watermark

Supports four watermark types for Word/PDF/OFD files:

• Fixed position text watermark (ApplyWatermark)
• Fixed position image watermark (ApplyPicWatermark)
• Tiled text watermark (ApplyWatermarkForFixed)
• Tiled image watermark (ApplyTiledImgWatermarkForFixed)

PPT files are automatically converted to PDF first before adding watermark.

• API: POST /publicapi/v1/content/update
• Controller: WatermarkController.java

Bookmark Content Replacement

Replaces bookmarks in a Word template with specified content, supporting three reference types:

• TEXT: Replace with plain text
• PIC: Replace with image (png/jpg)
• DOC: Replace with sub-document content (doc/docx/wps)

The project includes a built-in bookmark_template.docx template with 6 preset bookmarks for immediate testing.

• API: POST /publicapi/v1/content/update (actId: UpdateBookmarkRef)
• Controller: BookmarkController.java

Document Split

Supports splitting PDF and Word documents by page range, fixed page count, or keywords.

• API: POST /publicapi/v1/split
• Controller: DocSplitController.java

Stop the Service

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

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

References

• Open API Format Conversion
• Content Operations API
• Document Split