需求分析

• 文档可以和项目一起进行版本管理
• 文档可以在线访问
• 文档可以与springboot项目集成，不需要分开部署
• MarkDown支持
• 文档跟随，打包jar也可以访问

技术选型

对于网上已有的方案，大致分为如下几种

1. 将文档部署在 resource静态资源目录下，用模板渲染访问。\(^{[1]}\)
2. 分离部署，打包 jar后还需要单独上传静态资源文档内容并部署。

最终选定的技术方案如下

工具

用途

官网

Typora

文档编写

https://typoraio.cn/

Docsify

文档部署

https://docsify.js.org/#/

Hutool

服务集成

https://www.hutool.cn/docs/#/

工具介绍

Typora

Typora 是一款功能非常强大的 MarkDown编写工具，采用所见即所得的编辑方式，实现了即时预览的功能，Latex公式支持，具体请查看官网，目前只有平替，没有超越的MarkDown编写工具，对于本方案来讲，支持剪切图片直接保存到相对路径中，方便访问。同时也支持配置图床，需要使用PicGo搭建服务。

Docsify

docsify 可以自动地将 Markdown 中的标题生成目录，快速搭建一个小型的文档网站，整个页面的配色和布局也十分舒适，让阅读体验在不知不觉中提升了好几个档次。

和 Gitbook 不同，docsify 不会生成静态的 HTML 文件，它会智能地加载和解析 Markdown 文件，这就避免了 HTML 文件对整个文档库的“污染”。

还支持丰富的自定义样式。

Hutool

hutool 是一个非常好用的开发梭子，这种有大量用户使用的工具类，绝对比自己维护的轮子要稳定的多，所以开发选hutool是非常OK的一个选择。

我们使用的是hutool工具的一个子包 - SimpleServer

Oracle JDK提供了一个简单的Http服务端类，叫做HttpServer，当然它是sun的私有包，位于com.sun.net.httpserver下，必须引入rt.jar才能使用，Hutool基于此封装了SimpleServer，用于在不引入Tomcat、Jetty等容器的情况下，实现简单的Http请求处理。

功能实现

1. 初始化文档

在 resources 目录下，或者项目根目录下执行如下命令，在项目根目录执行，需要对 maven 打包进行额外的配置，推荐在 resources目录下执行。

docsify init .docs

2. 配置简易服务器

新建DocConfig.java

import cn.hutool.http.HttpUtil;
import org.springframework.context.annotation.Bean;
import org.springframework.stereotype.Component;
import java.io.File;

@Component
public class DocConfig {
    @Bean
    public void InitDoc(){
        String rootPath = System.getProperty("user.dir");

        HttpUtil.createServer(8888)
                // 设置默认根目录 -- resources目录下新建根据对应路径修改，目录分隔符用 File.separator 保证Win/Linux 兼容
                .setRoot(rootPath+ File.separator+".docs")
                .start();
    }
}

3. 访问

当启动 springboot 项目时，访问 localhost:8080即可访问对应文档

参考文档

[1] SpringBoot整合Docsify生成网站文档-每天学Java-腾讯云社区