告别Word写API接口！Docker+ShowDoc，写开发文档说明效率翻倍

一、Showdoc是什么？

一款开源、轻量、高效的在线 IT 文档协作工具

主打 API 接口文档、技术文档、数据字典、项目说明文档的编写与管理，适配个人开发者与中小技术团队使用。工具基于 Web 端运行，支持 Markdown 可视化编辑，具备文档版本管理、团队协作、权限管控、文档导出等能力，部署简单、轻量化无冗余功能，可快速搭建私有化专属文档服务，解决团队文档分散、版本混乱、同步低效、接口文档更新不及时等问题。

Apache‑2.0 协议开源轻量私有化文档工具，主打 API 接口文档

可通过官网查看示例：

https://www.showdoc.com.cn

image-20260908164356705

Github地址：https://github.com/star7th/showdoc

在线体验：https://www.showdoc.com.cn/demo/

在线演示站点可以直接体验全部编辑、接口模板、数据字典等全部功能

1.1、功能特点

• 轻量化文档编辑：原生支持 Markdown 语法，提供所见即所得可视化编辑模式，无需复杂操作即可排版美观的技术文档、接口文档，适配各类技术文档编写场景

• 完整版本管理：自动记录文档修改历史，支持版本回溯、对比与恢复，避免多人编辑导致的内容覆盖、版本混乱问题

• 精细化权限管控：支持公开项目、私密项目两种模式，私密项目可自定义访问密码，支持项目转让、成员权限区分，保障文档数据安全

• 便捷分享与导出：适配电脑、手机等多终端访问，支持文档链接分享，可一键导出 Word、HTML 格式文件，满足离线查阅、归档留存需求

• 自动化文档生成：支持解析代码注释自动生成接口文档，搭配 RunApi 工具可实现接口调试后自动同步更新文档，大幅减少手动编写成本

• 部署运维简单：支持 Docker 一键部署，无需复杂环境配置，资源占用极低，适配服务器、虚拟机、云主机等各类部署环境

1.2、使用场景介绍

1. API 接口文档管理：后端开发团队用于编写、维护前后端交互接口文档，统一接口入参、出参、请求方式、错误码规范，解决前后端对接沟通成本高、文档更新滞后问题

2. 项目技术知识库搭建：沉淀项目架构文档、部署文档、技术方案、问题排查手册，实现团队技术经验统一归档、共享复用

3. 数据字典维护：统一管理数据库表结构、字段说明、业务释义，规范团队数据认知，避免开发、测试、运维人员数据理解偏差

4. 团队协作文档共享：用于迭代需求说明、开发规范、测试用例、上线流程等协作文档的在线编辑与同步，替代本地文档、零散聊天文件传输方式

image-20260908164751736

1.3、和同类别产品对比

目前主流同类开源文档工具主要包含 Showdoc、Docmost、Wiki.js，三者均支持私有化部署与 Markdown 编辑，适配技术团队文档管理场景，核心差异对比如下：

• Showdoc：主打轻量化、极简易用，核心聚焦 API 文档与基础技术文档管理，部署资源占用极低、配置零门槛，兼容低配置服务器，支持代码注释自动生成文档、接口文档联动更新，适合中小开发团队、个人开发者，缺点是高级协作功能相对简约，不适合超大型团队复杂权限体系管理

• Docmost：界面现代化程度更高，支持富文本拓展、多维文档分类，团队协作功能更丰富，但部署配置相对复杂，资源占用高于 Showdoc，轻量化场景性价比偏低

• Wiki.js：功能全面、拓展性极强，支持多语言、多存储方式、丰富插件生态，适合企业级大型知识库搭建，但部署繁琐、学习成本高，冗余功能多，单纯用于接口文档管理过于厚重

Showdoc 整体界面简洁清爽，左侧为项目目录与文档树形结构，中间为编辑与预览区域，顶部为功能操作栏，无多余冗余模块

二、安装部署教程

本次部署基于 Docker 环境，支持 Docker Compose 批量部署与单命令快速部署两种方式，所有数据持久化至本地目录，避免容器删除数据丢失

2.1、创建本地文件夹目录

在服务器/opt 目录下创建 Showdoc 专属部署目录、数据持久化目录与配置目录

 # 创建Showdoc根目录  mkdir -p /opt/showdoc  # 创建数据持久化目录  mkdir -p /opt/showdoc/html

目录说明：所有容器运行产生的文档数据、配置信息、运行日志均持久化至本地目录，后续升级、重建容器不会丢失业务数据

2.2、Docker Compose 配置

在/opt/showdoc 目录下创建 docker-compose.yml 配置文件，写入完整部署配置：

 services:   showdoc:     image: star7th/showdoc:v3.7.3     container_name: showdoc     restart: always     privileged: true     user: root     ports:       - "10052:80"  # 左边是宿主机端口，可自行修改     volumes:       - ./html:/var/www/html  # 数据持久化到当前目录 html 文件夹

参数说明：

• image：指定 Showdoc 官方最新镜像，保证应用功能完整、安全可靠

• container_name：自定义容器名称，便于后续容器运维操作

• restart: always：设置容器开机自启、异常重启，保障服务持续在线

• ports：端口映射，将服务器10052端口映射容器80端口，可自定义对外访问端口

• volumes：数据挂载配置，实现文档数据、配置、日志本地持久化

启动命令（进入部署目录执行）：

 cd /opt/showdoc  docker-compose up -d

2.3、Docker 命令安装方式

1）下载Docker镜像

 docker pull star7th/showdoc:v3.7.3

2）使用Docker命令行启动

无需编写配置文件，直接执行单命令快速部署，适合快速搭建测试环境、简易生产环境：

 docker run -d    --name showdoc    --restart always    --privileged    --user root    -p 10052:80    -v ./html:/var/www/html   star7th/showdoc:v3.7.3

参数说明：

• -d：后台守护运行容器

• --name showdoc：容器名称

• --restart always：容器异常 / 开机自动重启

• --privileged：开启特权模式

• --user root：容器内部以 root 用户运行

• -p 10052:80：宿主机 10052 端口映射容器 80 端口，宿主机端口按需修改

• -v ./html:/var/www/html：将当前目录下html文件夹挂载容器完整程序目录，实现全部数据持久化

• star7th/showdoc:v3.7.3：指定固定 v3.7.3 版本镜像

部署完成后，放行服务器防火墙10052端口，通过 http://服务器IP:10052 即可访问 Showdoc 服务

三、使用教程

3.1、初始化设置

首次访问 http://服务器IP:10052 会自动进入初始化页面

1、设置语言界面

image-20260908170148557

2、初始化成功，默认管理员账户密码是showdoc/123456

登录后，在右上角可以看到管理后台入口。点击进入首页

image-20260908170218405

3、登录

使用showdoc/123456登录

image-20260908170357202

3.2、账号安全配置

进入首页后，点击页面右上角个人中心，找到账号设置模块，设置自定义管理员账号、登录密码。同时可开启访问权限管控，设置站点访问规则，禁止匿名恶意访问，完成基础安全防护配置。

个人设置

右上角用户中心-修改密码

修改用户昵称

image-20260908170524795

3.3、项目创建与文档编辑

点击首页新建项目，填写项目类型、项目名称、项目描述，选择项目类型（公开项目/私密项目），创建专属文档项目

项目类型支持日常、表格、白板、单页

image-20260908170814055

创建白板项目

image-20260908171213517

进入项目后，可通过左侧目录栏新建文档分类、新增文档页面，支持 Markdown 语法编辑接口文档、技术文档，编辑器支持代码块、表格、图片、列表等常用格式，适配各类技术文档编写需求。

image-20260908171258359

1）创建文档

通过模板创建文档

image-20260908171531127

使用API接口模板

image-20260908171608382

2）文档编辑

点击右上角，编辑页面按钮

编辑器为左右分栏布局，左侧编辑区、右侧实时预览，原生支持标准 Markdown 语法，支持代码块、表格、图片、列表、链接等常用排版元素CSDN博...。

3）查看历史记录

ShowDoc每次保存自动生成历史版本快照，记录修改人、修改时间，支持预览版本、对比差异、回滚恢复，误删误改可以找回内容CSDN博...

4）使用工具生成文档

这是由系统生成的APi文档示例项目。除了手动编辑文档外，你还可以通过以下三种方式生成文档：

1. ★ 使用RunApi工具自动生成（推荐）★

   https://www.showdoc.com.cn/runapi

2. 使用程序注释自动生成

   https://www.showdoc.com.cn/page/741656402509783

3. 自己写程序调用接口来生成

   https://www.showdoc.com.cn/page/102098

3.4、文档协作与分享

文档编辑完成后，可通过页面分享功能生成公开链接，分享给团队成员查阅。私密项目可设置独立访问密码，仅授权人员可查看编辑。支持多人在线协作编辑，系统自动记录修改痕迹，避免内容冲突。

3.5、文档导出与备份

单篇文档或整个项目支持一键导出为 Word、HTML 格式、markdown离线包，可用于离线归档、对外交付。同时依托本地挂载目录，可定期备份 /opt/showdoc/data 目录，实现文档数据全量备份，防止数据丢失。

四、Showdoc 使用技巧

4.1、接口文档标准化模板使用

Showdoc 内置专用 API 接口文档模板，新建文档时直接选用模板，模板预设请求地址、请求方式、请求参数、响应参数、错误码、示例代码等固定模块，无需手动排版，统一团队接口文档格式，大幅提升文档编写效率，规范接口文档输出标准。

4.2、版本回溯与内容对比

每一次文档保存都会自动生成版本记录，点击文档页面的版本历史功能，可查看所有修改记录，支持任意两个版本内容对比，清晰识别修改差异，误修改、误删除内容可一键回溯恢复

4.3、联动 RunApi 实现自动化文档更新

搭配官方 RunApi 接口调试工具使用，在 RunApi 中完成接口调试、参数修改后，可自动同步更新 Showdoc 对应接口文档，实现接口调试与文档更新一体化，彻底解决接口变更后文档更新不及时、文档与实际接口不一致的问题。

作者声明本文无利益相关，欢迎值友理性交流，和谐讨论～