我平时在公司里有个比较烦的事文档散落在各个地方写接口说明用 Word传文件用钉钉团队 Wiki 又没人维护时间一长根本不知道哪份才是最新的。后来我专门去 GitHub 上找了一圈文档工具发现几个开源项目确实能解决这类问题而且都是可以直接部署或者集成到现有流程里的。这篇文章就把我筛选过的 4 个有代表性的项目拿出来聊聊包括它们的核心功能、适用场景、我实际用下来的感受以及一些配置和踩坑记录。如果你也在为接口文档、文档转换、团队知识库或者批量解析文档发愁可以参考一下。1. 先聊聊我挑选文档工具的思路在逐个介绍项目之前我想先说清楚自己是按什么标准挑的。GitHub 上标了“documentation”“docs”的项目特别多但很多其实只是某个框架的附属说明真正能独立拿出来用的工具并没有想象中那么多。我这次主要看四件事第一是解决的是不是高频难题。接口文档怎么写、格式怎么转、文档站怎么搭、PDF 内容怎么批量提取这些几乎每一个开发团队或者做内容的人都会碰到。如果项目本身解决的问题太冷门就算代码写得再漂亮实际用上的概率也很低。第二是社区活跃度。GitHub 上的 Star 数量一定程度上能反映项目受欢迎程度但我更在意的是最近一年有没有持续提交、Issue 响应快不快、有没有人在维护文档和示例。一个半年没更新的项目就算 Star 再高用到一半遇到 Bug 也没人管体验会很难受。第三是部署和使用成本。有些工具功能很强但要搭一堆依赖、配一堆环境小团队根本折腾不起。我希望找到的是那种能快速跑起来、又能被方便集成到 CI/CD 或者内部系统里的项目。第四是是否足够开放。既然选择开源就希望它不锁定在某个商业平台数据能自由导出二次开发也有文档指引。这样即使以后项目作者不维护了团队自己也能接手改。在这四条标准下我最终挑出了 4 个项目分别对应接口文档自动生成、文档格式转换、静态文档站搭建、文档内容解析提取这四个方向。接下来逐个详细介绍。2. 接口文档自动生成springdoc-openapi先说接口文档这应该是最多人有切肤之痛的方向。传统做法是用 Word 写接口说明前端要看的时候到处找人要最新版等接口改了文档又忘了改最后文档就成了一堆永远对不上的历史垃圾。springdoc-openapi 这个项目解决的就是“代码即文档”的问题它自动扫描 Spring Boot 项目里的 Controller把接口路径、请求参数、响应结构全部抓出来按照 OpenAPI 3 规范生成一份可交互的 API 文档。2.1 为什么不用 Swagger 注解而选它老项目可能还在用 springfox但那玩意已经很久没更新了对 Spring Boot 2.6 之后的路由匹配策略支持得很差。springdoc-openapi 是新一代方案原生支持 OpenAPI 3和 Spring Boot 融合度好很多基本只要引入依赖就能跑起来。我在一个订单服务里试过引入依赖后访问/swagger-ui.html所有接口就直接列出来了。如果代码里的实体类写得规范响应结构也能猜得八九不离十。更关键的是它支持分组比如按模块拆成order-api、user-api前端同学只需要关注自己负责的那部分不用在一堆接口里翻来翻去。2.2 最小接入配置示例我用的是 Gradle 项目第一步先加依赖implementation org.springdoc:springdoc-openapi-starter-webmvc-ui:2.5.0然后加一个基础配置类定义好全局信息import io.swagger.v3.oas.models.OpenAPI; import io.swagger.v3.oas.models.info.Info; import org.springframework.context.annotation.Bean; import org.springframework.context.annotation.Configuration; Configuration public class OpenApiConfig { Bean public OpenAPI customOpenAPI() { return new OpenAPI() .info(new Info() .title(订单服务 API) .version(v1.0.0) .description(供前端与第三方对接使用的接口文档)); } }接着在 Controller 里补充必要的注解。虽然不写也能生成基础文档但Tag、Operation、Parameter这些注解能让文档可读性高很多。比如import io.swagger.v3.oas.annotations.Operation; import io.swagger.v3.oas.annotations.tags.Tag; import org.springframework.web.bind.annotation.*; Tag(name 订单查询, description 订单相关查询接口) RestController RequestMapping(/api/order) public class OrderController { Operation(summary 查询订单详情, description 根据订单号查询订单详细信息) GetMapping(/{orderNo}) public OrderDetail getOrder(PathVariable String orderNo) { // 实际业务逻辑 return new OrderDetail(); } }启动服务后访问http://localhost:8080/swagger-ui.html就能看到交互页面每个接口还可以直接点“Try it out”调试后端不用专门部署 postman 合集排查问题时方便很多。2.3 我踩过的坑和心得第一个坑是实体类循环引用。如果有 A 引用 B、B 又引用 A 这种关系生成的文档会直接递归OpenAPI 描述里出现$ref死循环。解决办法是在实体类上用JsonIgnore或者Schema(hidden true)把不需要展示的字段标掉保证输出简洁。第二个坑是鉴权接口的文档化。很多接口需要带 Token如果不在配置里声明全局安全方案前端拿文档去调试时还要手动去复制 token体验很割裂。可以在配置文件里加springdoc: swagger-ui: persist-authorization: true同时在代码里配置安全方案这样前端在页面上输入一次 token后续请求都会自动带上不用反复填。第三个提醒是文档生成依赖代码规范。如果 POJO 里全是 Map 类型或者参数直接接收HttpServletRequest那生成出来的文档基本没什么可读性。想让文档好看代码层就要尽量用明确的 DTO。3. 文档格式转换Pandoc第二款是 Pandoc准确说它不是新项目但在这个选题里它绝对是不可跳过的一个。Pandoc 被称为“文档转换的瑞士军刀”能处理的格式超过几十种从 Markdown、HTML、LaTeX 到 docx、epub、PDF甚至 reStructuredText、Org 文件都没有问题。我之前做技术方案时经常要把 Markdown 转成 Word 给产品同事批注用 Pandoc 一行命令就能完成。3.1 最常用的几种转换命令我的主力用法是把它接到脚本里批量处理文件。比如把当前目录下面所有.md文件转成.docxfor f in *.md; do pandoc $f -o ${f%.md}.docx done如果想把多份文档合成一份完整的 Word 报告pandoc chapter1.md chapter2.md chapter3.md -o final-report.docx它还会保留 Markdown 里的标题层级自动映射到 Word 的标题样式。这意味着转出来的文档不是一坨纯文本而是带着大纲结构的正式文档排版基本不用再调整。除了 Word转 PDF 也很常用。Pandoc 转 PDF 依赖 LaTeX 引擎我习惯用xelatex处理中文pandoc README.md -o README.pdf --pdf-enginexelatex -V CJKmainfontNoto Sans CJK SC如果不指定CJKmainfont中文大概率会变成方块乱码。这个问题我第一次用的时候栽过后来直接在配置里固定写了字体参数才彻底稳定。3.2 利用模板和变量定制输出效果Pandoc 最强的一点是可以自定义 Word 模板。我第一次生成 docx 后发现字体和页边距跟公司要求的格式不一致逐个改太痛苦。后来用 Pandoc 自带的模板导出功能解决pandoc -o custom-reference.docx --print-default-data-file reference.docx custom-reference.docx然后打开custom-reference.docx手动调整样式比如把正文改成宋体五号、标题改成黑体三号保存后再通过参数指定pandoc input.md -o output.docx --reference-doccustom-reference.docx这样生成的每个 Word 文件都会套用公司标准样式特别适合那种定期要输出交付报告的团队。3.3 使用注意事项Pandoc 看起来是“转完就完事”但有几个细节会影响输出质量表格语法要规范。GitHub 风格表格在 Pandoc 里默认支持但如果单元格内有换行最好用 HTML 表格语法否则转换时容易错位。图片路径要是相对路径。转 Word 时如果图片使用绝对路径或者网络 URL可能会显示异常尽量把图片放在同目录并用相对路径引用。CSS 对 PDF 输出无效。Pandoc 不是浏览器不会执行样式渲染所有视觉表现都靠模板和 LaTeX 变量实现。想调颜色、边距得去模板层改。我的体会是 Pandoc 能极大减轻文档交付的重复劳动但前提是你愿意花半小时理解模板机制。一旦定制好自己的 reference 文件后面所有转换都是零成本。4. 静态文档站搭建VitePress第三个项目是 VitePress。它是一个专为技术文档打造的静态站点生成器基于 Vite 和 Vue 3主题非常清爽自带搜索、导航栏、侧边栏。相比 GitBook 这类老牌方案VitePress 构建速度极快写文档的时候还能实时预览体验有点像写代码配了热更新。4.1 适合什么场景如果你需要搭一个团队内部知识库或者给开源项目做文档官网VitePress 是非常合适的选择。它不像 Confluence 那样重也不像语雀那样把内容锁在平台里所有文档就是 Markdown 文件放在 Git 仓库里天然支持版本管理、多人协作、代码评审流程。我搭团队文档站的时候就把架构设计、接口约定、部署手册这些内容全部用 Markdown 写好推到 Git 仓库后触发构建自动发布到内部服务器。谁改了文档、改了什么全都看得清清楚楚。再也没出现过“文档被谁覆盖了”的扯皮。4.2 快速搭建步骤初始化一个 VitePress 项目非常简单npm create vitejs/app my-docs --template vue cd my-docs npm install vitepress --save-dev然后创建目录结构和首页配置mkdir docs touch docs/index.mddocs/index.md里写--- layout: home hero: name: 团队技术文档 text: 架构、接口与最佳实践 --- 欢迎来到这里。接着在docs/.vitepress/config.js里配置导航和侧边栏export default { title: 团队技术文档, description: 内部知识库, themeConfig: { nav: [ { text: 指南, link: /guide/ }, { text: API, link: /api/ }, ], sidebar: { /guide/: [ { text: 介绍, link: /guide/introduction }, { text: 部署, link: /guide/deployment }, ], }, }, };运行npm run docs:dev浏览器打开本地地址就能看到效果改 Markdown 内容会自动刷新页面。构建发布时执行npm run docs:build输出目录在docs/.vitepress/dist把这个目录扔到 Nginx 或对象存储上就能访问。4.3 部署小技巧VitePress 站点的文件名和路径直接决定 URL 结构所以要提前规划目录。我的习惯是把文档按模块拆成一级目录server/、web/、ops/每个目录里再分guide/、api/等二级目录这样侧边栏配置和搜索引擎结构都很清晰。另外 VitePress 支持 Markdown 内嵌 Vue 组件这意味着你可以在文档里写动态示例、放代码演示甚至接一个在线 API 调试工具。对开发者来说这种“文档即产品”的体验比纯静态页面好用得多。5. 文档内容解析与提取Apache Tika第四个项目和前面几个不大一样它不负责生成文档而是专门做“读懂文档”这件事。Apache Tika 是一个内容解析工具包能从 PDF、Word、Excel、PPT、HTML 等文件里抽取文本和元数据。做搜索、知识库、内容审核这类系统时它就是最常用的一层解析底座。5.1 用 Tika 解决批量文本提取举个例子假如你有一批 PDF 合同文件需要提取里面的文本内容入库做全文检索。直接用 Python 处理 PDF 会有很多坑比如扫描件没有文本层、排版分栏导致读取顺序混乱。Tika 对常见格式的处理能力比较成熟很多奇怪的文件类型它都能识别。Tika 提供多种调用方式服务器模式最方便。把 Tika 跑成一个 HTTP 服务其他系统只需要 POST 文件上去就能拿回提取后的纯文本java -jar tika-server-standard-2.9.0.jar --port 9998然后调用接口curl -X PUT --data-binary test.pdf http://localhost:9998/tika --header Content-Type: application/pdf返回的就是从 PDF 里抽取出来的纯文本。我在做文档知识库系统时就采用这种方式把 PDF 合同、Word 协议、Excel 表格都统一 parse 成文本再灌入 Elasticsearch。无论前端传什么格式过来解析层都只要打一个接口就行。5.2 和其他解析工具对比市面上有很多 PDF 解析库比如 Python 的 pdfplumber、PyMuPDF、Java 的 PDFBox。这些库对单一格式处理效果很好但如果团队面临的是“多格式混合输入”每个格式单独接一个库的成本会很高而且格式越复杂越容易出问题。Tika 的价值在于它把格式差异隐藏起来了。底层它可能还是会调用 PDFBox、POI 这些库但对外暴露的是统一的接口而且能自动根据 MIME 类型匹配解析器。多格式混合场景下用 Tika 作为统一入口要比自己拼接各种库省心得多。5.3 两个典型的坑第一个坑是解析时间太长。有些 PDF 内部图像和字体资源非常多Tika 处理一次可能要几十秒甚至更久。如果是高并发接口调用很容易把线程池占满。我的建议是不要同步等待 Tika 返回改成异步任务方式文件上传后先返回一个任务 ID解析完成后回调通知结果。第二个坑是识别 OCR 还是非 OCR。Tika 默认不带 OCR 功能对扫描版 PDF 只能提取出空文本。如果要处理扫描件需要额外集成 Tesseract OCR 库并配置--ocr相关参数。这一步实际效果比较依赖图像质量不能指望全能。更稳妥的做法是在系统里区分“文本型 PDF”和“扫描型 PDF”扫描型走专门的 OCR 处理流程。6. 常见问题与排查技巧实录既然一次聊了四个项目我把实际使用中遇到的几个高频问题集中整理一下方便大家遇到类似情况时不用从头排查。6.1 springdoc-openapi 文档页面打不开大概率是路径被安全框架拦截了。Spring Security 默认会拦截所有请求需要把/swagger-ui/**、/v3/api-docs/**这几个端点放行。另一个常见原因是项目使用了自定义context-path比如服务跑在/api前缀下访问文档时也要把前缀加上否则 URL 对不上。6.2 Pandoc 转 PDF 中文乱码核心原因是 LaTeX 引擎默认字体不支持中文。安装一个支持中文的字体例如 Noto Sans CJK SC然后在命令里通过-V CJKmainfont指定。还有一个小坑Windows 系统上的字体名称和字体文件名称不一致最好先用fc-list查看系统实际识别的字体名再配置到变量里。6.3 VitePress 构建后图片丢失最常见的场景是图片放在public目录外面但在 Markdown 里用了绝对路径引用。VitePress 对 Markdown 里的图片资源做了构建处理引用方式必须符合它的规范。建议统一把公共图片放到docs/public目录然后用/图片名.png的方式引用这样构建前后路径都不会乱。6.4 Tika 解析大文件内存溢出Tika Server 默认堆内存如果设置偏小解析大型 PDF 会直接 OOM。可以启动时加大内存java -Xmx4g -jar tika-server-standard-2.9.0.jar --port 9998如果还是频繁 OOM需要检查是不是有超大文件持续进来建议对单文件大小做上限控制比如超过 100MB 的文件直接走额外的离线解析通道而不是挤占在线服务资源。6.5 结合 AI 工具提效的延伸思路顺便提一个现在很实用的扩展方向文档解析完之后的文本结果可以直接作为 Prompt 的上下文喂给大模型做摘要或者问答。比如技术团队把接口文档、运维手册解析后统一存库再通过问答机器人的方式提供服务新同学入职后不用翻几十篇文档直接在内部聊天工具里问一句“测试环境怎么部署”机器人就能从文档中检索答案。这一套流程里springdoc-openapi 负责产出接口数据VitePress 负责展示整体文档Tika 负责把历史格式文档变成可消费的文本Pandoc 则负责把散落的碎片转换成统一格式。四个工具组合起来基本覆盖了我日常工作中 90% 以上的文档处理需求。我个人最推荐的组合是接口文档用 springdoc-openapi知识库用 VitePress历史文件解析用 Tika格式转换用 Pandoc。如果只能选一个先落地我会建议从 springdoc-openapi 开始因为它能立刻解决接口文档和维护脱节的问题而且团队成员几乎没有学习成本。等这套跑顺了再逐步引入其他工具你会发现整个团队的文档协作能顺畅很多。
我平时在公司里有个比较烦的事文档散落在各个地方写接口说明用 Word传文件用钉钉团队 Wiki 又没人维护时间一长根本不知道哪份才是最新的。后来我专门去 GitHub 上找了一圈文档工具发现几个开源项目确实能解决这类问题而且都是可以直接部署或者集成到现有流程里的。这篇文章就把我筛选过的 4 个有代表性的项目拿出来聊聊包括它们的核心功能、适用场景、我实际用下来的感受以及一些配置和踩坑记录。如果你也在为接口文档、文档转换、团队知识库或者批量解析文档发愁可以参考一下。1. 先聊聊我挑选文档工具的思路在逐个介绍项目之前我想先说清楚自己是按什么标准挑的。GitHub 上标了“documentation”“docs”的项目特别多但很多其实只是某个框架的附属说明真正能独立拿出来用的工具并没有想象中那么多。我这次主要看四件事第一是解决的是不是高频难题。接口文档怎么写、格式怎么转、文档站怎么搭、PDF 内容怎么批量提取这些几乎每一个开发团队或者做内容的人都会碰到。如果项目本身解决的问题太冷门就算代码写得再漂亮实际用上的概率也很低。第二是社区活跃度。GitHub 上的 Star 数量一定程度上能反映项目受欢迎程度但我更在意的是最近一年有没有持续提交、Issue 响应快不快、有没有人在维护文档和示例。一个半年没更新的项目就算 Star 再高用到一半遇到 Bug 也没人管体验会很难受。第三是部署和使用成本。有些工具功能很强但要搭一堆依赖、配一堆环境小团队根本折腾不起。我希望找到的是那种能快速跑起来、又能被方便集成到 CI/CD 或者内部系统里的项目。第四是是否足够开放。既然选择开源就希望它不锁定在某个商业平台数据能自由导出二次开发也有文档指引。这样即使以后项目作者不维护了团队自己也能接手改。在这四条标准下我最终挑出了 4 个项目分别对应接口文档自动生成、文档格式转换、静态文档站搭建、文档内容解析提取这四个方向。接下来逐个详细介绍。2. 接口文档自动生成springdoc-openapi先说接口文档这应该是最多人有切肤之痛的方向。传统做法是用 Word 写接口说明前端要看的时候到处找人要最新版等接口改了文档又忘了改最后文档就成了一堆永远对不上的历史垃圾。springdoc-openapi 这个项目解决的就是“代码即文档”的问题它自动扫描 Spring Boot 项目里的 Controller把接口路径、请求参数、响应结构全部抓出来按照 OpenAPI 3 规范生成一份可交互的 API 文档。2.1 为什么不用 Swagger 注解而选它老项目可能还在用 springfox但那玩意已经很久没更新了对 Spring Boot 2.6 之后的路由匹配策略支持得很差。springdoc-openapi 是新一代方案原生支持 OpenAPI 3和 Spring Boot 融合度好很多基本只要引入依赖就能跑起来。我在一个订单服务里试过引入依赖后访问/swagger-ui.html所有接口就直接列出来了。如果代码里的实体类写得规范响应结构也能猜得八九不离十。更关键的是它支持分组比如按模块拆成order-api、user-api前端同学只需要关注自己负责的那部分不用在一堆接口里翻来翻去。2.2 最小接入配置示例我用的是 Gradle 项目第一步先加依赖implementation org.springdoc:springdoc-openapi-starter-webmvc-ui:2.5.0然后加一个基础配置类定义好全局信息import io.swagger.v3.oas.models.OpenAPI; import io.swagger.v3.oas.models.info.Info; import org.springframework.context.annotation.Bean; import org.springframework.context.annotation.Configuration; Configuration public class OpenApiConfig { Bean public OpenAPI customOpenAPI() { return new OpenAPI() .info(new Info() .title(订单服务 API) .version(v1.0.0) .description(供前端与第三方对接使用的接口文档)); } }接着在 Controller 里补充必要的注解。虽然不写也能生成基础文档但Tag、Operation、Parameter这些注解能让文档可读性高很多。比如import io.swagger.v3.oas.annotations.Operation; import io.swagger.v3.oas.annotations.tags.Tag; import org.springframework.web.bind.annotation.*; Tag(name 订单查询, description 订单相关查询接口) RestController RequestMapping(/api/order) public class OrderController { Operation(summary 查询订单详情, description 根据订单号查询订单详细信息) GetMapping(/{orderNo}) public OrderDetail getOrder(PathVariable String orderNo) { // 实际业务逻辑 return new OrderDetail(); } }启动服务后访问http://localhost:8080/swagger-ui.html就能看到交互页面每个接口还可以直接点“Try it out”调试后端不用专门部署 postman 合集排查问题时方便很多。2.3 我踩过的坑和心得第一个坑是实体类循环引用。如果有 A 引用 B、B 又引用 A 这种关系生成的文档会直接递归OpenAPI 描述里出现$ref死循环。解决办法是在实体类上用JsonIgnore或者Schema(hidden true)把不需要展示的字段标掉保证输出简洁。第二个坑是鉴权接口的文档化。很多接口需要带 Token如果不在配置里声明全局安全方案前端拿文档去调试时还要手动去复制 token体验很割裂。可以在配置文件里加springdoc: swagger-ui: persist-authorization: true同时在代码里配置安全方案这样前端在页面上输入一次 token后续请求都会自动带上不用反复填。第三个提醒是文档生成依赖代码规范。如果 POJO 里全是 Map 类型或者参数直接接收HttpServletRequest那生成出来的文档基本没什么可读性。想让文档好看代码层就要尽量用明确的 DTO。3. 文档格式转换Pandoc第二款是 Pandoc准确说它不是新项目但在这个选题里它绝对是不可跳过的一个。Pandoc 被称为“文档转换的瑞士军刀”能处理的格式超过几十种从 Markdown、HTML、LaTeX 到 docx、epub、PDF甚至 reStructuredText、Org 文件都没有问题。我之前做技术方案时经常要把 Markdown 转成 Word 给产品同事批注用 Pandoc 一行命令就能完成。3.1 最常用的几种转换命令我的主力用法是把它接到脚本里批量处理文件。比如把当前目录下面所有.md文件转成.docxfor f in *.md; do pandoc $f -o ${f%.md}.docx done如果想把多份文档合成一份完整的 Word 报告pandoc chapter1.md chapter2.md chapter3.md -o final-report.docx它还会保留 Markdown 里的标题层级自动映射到 Word 的标题样式。这意味着转出来的文档不是一坨纯文本而是带着大纲结构的正式文档排版基本不用再调整。除了 Word转 PDF 也很常用。Pandoc 转 PDF 依赖 LaTeX 引擎我习惯用xelatex处理中文pandoc README.md -o README.pdf --pdf-enginexelatex -V CJKmainfontNoto Sans CJK SC如果不指定CJKmainfont中文大概率会变成方块乱码。这个问题我第一次用的时候栽过后来直接在配置里固定写了字体参数才彻底稳定。3.2 利用模板和变量定制输出效果Pandoc 最强的一点是可以自定义 Word 模板。我第一次生成 docx 后发现字体和页边距跟公司要求的格式不一致逐个改太痛苦。后来用 Pandoc 自带的模板导出功能解决pandoc -o custom-reference.docx --print-default-data-file reference.docx custom-reference.docx然后打开custom-reference.docx手动调整样式比如把正文改成宋体五号、标题改成黑体三号保存后再通过参数指定pandoc input.md -o output.docx --reference-doccustom-reference.docx这样生成的每个 Word 文件都会套用公司标准样式特别适合那种定期要输出交付报告的团队。3.3 使用注意事项Pandoc 看起来是“转完就完事”但有几个细节会影响输出质量表格语法要规范。GitHub 风格表格在 Pandoc 里默认支持但如果单元格内有换行最好用 HTML 表格语法否则转换时容易错位。图片路径要是相对路径。转 Word 时如果图片使用绝对路径或者网络 URL可能会显示异常尽量把图片放在同目录并用相对路径引用。CSS 对 PDF 输出无效。Pandoc 不是浏览器不会执行样式渲染所有视觉表现都靠模板和 LaTeX 变量实现。想调颜色、边距得去模板层改。我的体会是 Pandoc 能极大减轻文档交付的重复劳动但前提是你愿意花半小时理解模板机制。一旦定制好自己的 reference 文件后面所有转换都是零成本。4. 静态文档站搭建VitePress第三个项目是 VitePress。它是一个专为技术文档打造的静态站点生成器基于 Vite 和 Vue 3主题非常清爽自带搜索、导航栏、侧边栏。相比 GitBook 这类老牌方案VitePress 构建速度极快写文档的时候还能实时预览体验有点像写代码配了热更新。4.1 适合什么场景如果你需要搭一个团队内部知识库或者给开源项目做文档官网VitePress 是非常合适的选择。它不像 Confluence 那样重也不像语雀那样把内容锁在平台里所有文档就是 Markdown 文件放在 Git 仓库里天然支持版本管理、多人协作、代码评审流程。我搭团队文档站的时候就把架构设计、接口约定、部署手册这些内容全部用 Markdown 写好推到 Git 仓库后触发构建自动发布到内部服务器。谁改了文档、改了什么全都看得清清楚楚。再也没出现过“文档被谁覆盖了”的扯皮。4.2 快速搭建步骤初始化一个 VitePress 项目非常简单npm create vitejs/app my-docs --template vue cd my-docs npm install vitepress --save-dev然后创建目录结构和首页配置mkdir docs touch docs/index.mddocs/index.md里写--- layout: home hero: name: 团队技术文档 text: 架构、接口与最佳实践 --- 欢迎来到这里。接着在docs/.vitepress/config.js里配置导航和侧边栏export default { title: 团队技术文档, description: 内部知识库, themeConfig: { nav: [ { text: 指南, link: /guide/ }, { text: API, link: /api/ }, ], sidebar: { /guide/: [ { text: 介绍, link: /guide/introduction }, { text: 部署, link: /guide/deployment }, ], }, }, };运行npm run docs:dev浏览器打开本地地址就能看到效果改 Markdown 内容会自动刷新页面。构建发布时执行npm run docs:build输出目录在docs/.vitepress/dist把这个目录扔到 Nginx 或对象存储上就能访问。4.3 部署小技巧VitePress 站点的文件名和路径直接决定 URL 结构所以要提前规划目录。我的习惯是把文档按模块拆成一级目录server/、web/、ops/每个目录里再分guide/、api/等二级目录这样侧边栏配置和搜索引擎结构都很清晰。另外 VitePress 支持 Markdown 内嵌 Vue 组件这意味着你可以在文档里写动态示例、放代码演示甚至接一个在线 API 调试工具。对开发者来说这种“文档即产品”的体验比纯静态页面好用得多。5. 文档内容解析与提取Apache Tika第四个项目和前面几个不大一样它不负责生成文档而是专门做“读懂文档”这件事。Apache Tika 是一个内容解析工具包能从 PDF、Word、Excel、PPT、HTML 等文件里抽取文本和元数据。做搜索、知识库、内容审核这类系统时它就是最常用的一层解析底座。5.1 用 Tika 解决批量文本提取举个例子假如你有一批 PDF 合同文件需要提取里面的文本内容入库做全文检索。直接用 Python 处理 PDF 会有很多坑比如扫描件没有文本层、排版分栏导致读取顺序混乱。Tika 对常见格式的处理能力比较成熟很多奇怪的文件类型它都能识别。Tika 提供多种调用方式服务器模式最方便。把 Tika 跑成一个 HTTP 服务其他系统只需要 POST 文件上去就能拿回提取后的纯文本java -jar tika-server-standard-2.9.0.jar --port 9998然后调用接口curl -X PUT --data-binary test.pdf http://localhost:9998/tika --header Content-Type: application/pdf返回的就是从 PDF 里抽取出来的纯文本。我在做文档知识库系统时就采用这种方式把 PDF 合同、Word 协议、Excel 表格都统一 parse 成文本再灌入 Elasticsearch。无论前端传什么格式过来解析层都只要打一个接口就行。5.2 和其他解析工具对比市面上有很多 PDF 解析库比如 Python 的 pdfplumber、PyMuPDF、Java 的 PDFBox。这些库对单一格式处理效果很好但如果团队面临的是“多格式混合输入”每个格式单独接一个库的成本会很高而且格式越复杂越容易出问题。Tika 的价值在于它把格式差异隐藏起来了。底层它可能还是会调用 PDFBox、POI 这些库但对外暴露的是统一的接口而且能自动根据 MIME 类型匹配解析器。多格式混合场景下用 Tika 作为统一入口要比自己拼接各种库省心得多。5.3 两个典型的坑第一个坑是解析时间太长。有些 PDF 内部图像和字体资源非常多Tika 处理一次可能要几十秒甚至更久。如果是高并发接口调用很容易把线程池占满。我的建议是不要同步等待 Tika 返回改成异步任务方式文件上传后先返回一个任务 ID解析完成后回调通知结果。第二个坑是识别 OCR 还是非 OCR。Tika 默认不带 OCR 功能对扫描版 PDF 只能提取出空文本。如果要处理扫描件需要额外集成 Tesseract OCR 库并配置--ocr相关参数。这一步实际效果比较依赖图像质量不能指望全能。更稳妥的做法是在系统里区分“文本型 PDF”和“扫描型 PDF”扫描型走专门的 OCR 处理流程。6. 常见问题与排查技巧实录既然一次聊了四个项目我把实际使用中遇到的几个高频问题集中整理一下方便大家遇到类似情况时不用从头排查。6.1 springdoc-openapi 文档页面打不开大概率是路径被安全框架拦截了。Spring Security 默认会拦截所有请求需要把/swagger-ui/**、/v3/api-docs/**这几个端点放行。另一个常见原因是项目使用了自定义context-path比如服务跑在/api前缀下访问文档时也要把前缀加上否则 URL 对不上。6.2 Pandoc 转 PDF 中文乱码核心原因是 LaTeX 引擎默认字体不支持中文。安装一个支持中文的字体例如 Noto Sans CJK SC然后在命令里通过-V CJKmainfont指定。还有一个小坑Windows 系统上的字体名称和字体文件名称不一致最好先用fc-list查看系统实际识别的字体名再配置到变量里。6.3 VitePress 构建后图片丢失最常见的场景是图片放在public目录外面但在 Markdown 里用了绝对路径引用。VitePress 对 Markdown 里的图片资源做了构建处理引用方式必须符合它的规范。建议统一把公共图片放到docs/public目录然后用/图片名.png的方式引用这样构建前后路径都不会乱。6.4 Tika 解析大文件内存溢出Tika Server 默认堆内存如果设置偏小解析大型 PDF 会直接 OOM。可以启动时加大内存java -Xmx4g -jar tika-server-standard-2.9.0.jar --port 9998如果还是频繁 OOM需要检查是不是有超大文件持续进来建议对单文件大小做上限控制比如超过 100MB 的文件直接走额外的离线解析通道而不是挤占在线服务资源。6.5 结合 AI 工具提效的延伸思路顺便提一个现在很实用的扩展方向文档解析完之后的文本结果可以直接作为 Prompt 的上下文喂给大模型做摘要或者问答。比如技术团队把接口文档、运维手册解析后统一存库再通过问答机器人的方式提供服务新同学入职后不用翻几十篇文档直接在内部聊天工具里问一句“测试环境怎么部署”机器人就能从文档中检索答案。这一套流程里springdoc-openapi 负责产出接口数据VitePress 负责展示整体文档Tika 负责把历史格式文档变成可消费的文本Pandoc 则负责把散落的碎片转换成统一格式。四个工具组合起来基本覆盖了我日常工作中 90% 以上的文档处理需求。我个人最推荐的组合是接口文档用 springdoc-openapi知识库用 VitePress历史文件解析用 Tika格式转换用 Pandoc。如果只能选一个先落地我会建议从 springdoc-openapi 开始因为它能立刻解决接口文档和维护脱节的问题而且团队成员几乎没有学习成本。等这套跑顺了再逐步引入其他工具你会发现整个团队的文档协作能顺畅很多。
