meTypeset HTTP API

将 Microsoft Word (.docx) 与元数据 (metadata XML) 转换为 JATS / NLM XML 的接口

基础地址 http://localhost:8000 单容器部署

1. 接口总览

方法路径说明
GET /health 健康检查，返回服务状态。
POST /api/v1/convert 上传 docx（可选元数据），返回 JATS XML。
GET / 或 /docs 本说明文档。

2. 转换接口

请求

POST/api/v1/convert

Content-Type 使用 multipart/form-data。

表单字段

字段类型必填默认说明
file文件是-待转换的 Word .docx 文件。
metadata文件否-元数据 XML 文件（JATS <article-meta> / <journal-meta> 结构）。不传则使用内置 metadata/metadataSample.xml。
aggression整数否10解析激进程度 0-10，越大启用的分类器越多。
clean布尔否false是否输出清理后的最终 XML（对应 -c）。
identifiers布尔否false是否为支持的 NLM 元素生成唯一 id（对应 -i）。
nolink布尔否false跳过参考文献链接器（对应 --nolink）。
nometa布尔否false不合并前置元数据（对应 --nometa）。
references文件 / 文本否-给定参考文献（纯文本，每行一条）。提供后用其替换 JATS 的 <back><ref-list>，不再使用 docx 提取结果。可传文件 -F "references=@refs.txt"，或直接传文本字段 -F "references=..."。
布尔字段传 1 / true / yes / on 均视为真，其余视为假。

输出格式

通过 output 参数选择返回类型（也可用 format 或请求头 Accept）：

output返回Content-Type说明
xml（默认）纯 JATS XMLapplication/xml只返回正文 XML，不含图片。
zipZIP 压缩包application/zip含 article.xml + media/* 图片，推荐用于完整交付。
jsonJSONapplication/json{"filename","jats"} 结构。

ZIP 包内部结构（与 JATS 中 xlink:href="media/xxx" 对齐）：

article.xml
media/
  image1.png
  image2.jpg

JSON 返回结构：

{
  "filename": "article.xml",
  "jats": "<?xml version=\"1.0\"...>...</article>"
}

3. 响应

状态码含义
200转换成功，按 output 返回 JATS XML / ZIP / JSON。
400缺少 file 字段或文件名为空。
500转换失败，返回 stdout/stderr 尾部日志。

4. 示例

4.1 仅转换 docx（使用默认元数据）

curl -X POST http://localhost:8000/api/v1/convert \
  -F "file=@./tests/Sec004.docx" \
  -o result.xml

4.2 附带自定义元数据

curl -X POST http://localhost:8000/api/v1/convert \
  -F "file=@./my-article.docx" \
  -F "metadata=@./metadata/metadataSample.xml" \
  -F "aggression=10" \
  -F "clean=1" \
  -o result.xml

4.3 给定参考文献（替换 docx 提取结果）

# references.txt：每行一条参考文献
curl -X POST "http://localhost:8000/api/v1/convert?output=zip" \
  -F "file=@./my-article.docx" \
  -F "references=@./references.txt" \
  -o result.zip

# 或直接传文本字段
curl -X POST "http://localhost:8000/api/v1/convert" \
  -F "file=@./my-article.docx" \
  -F "references=Smith J. Title of paper. Journal. 2020;1(1):1-10."

4.4 以 ZIP 返回（含图片）

curl -X POST "http://localhost:8000/api/v1/convert?output=zip" \
  -F "file=@./my-article.docx" \
  -o result.zip

4.5 以 JSON 返回

curl -X POST "http://localhost:8000/api/v1/convert?output=json" \
  -F "file=@./my-article.docx" \
  -H "Accept: application/json"

4.6 健康检查

curl http://localhost:8000/health

5. Docker 部署

在项目根目录（与 Dockerfile 同级）执行：

# 方式一：docker compose
docker compose up -d --build

# 方式二：手动构建并运行
docker build -t metypeset-api .
docker run -d -p 8000:8000 --name metypeset-api metypeset-api

访问 http://localhost:8000/docs 查看本说明。

6. 能力与限制