springboot 集成 docsify 實現隨身文檔

2022 年 9 月 8 日
筆記
JAVA, springboot

需求分析

文檔可以和項目一起進行版本管理
文檔可以在線訪問
文檔可以與springboot項目集成，不需要分開部署
MarkDown支持
文檔跟隨，打包jar也可以訪問

技術選型

對於網上已有的方案，大致分為如下幾種

將文檔部署在 resource靜態資源目錄下，用模板渲染訪問。\(^{[1]}\)
分離部署，打包 jar後還需要單獨上傳靜態資源文檔內容並部署。

最終選定的技術方案如下

工具	用途	官網
Typora	文檔編寫	//typoraio.cn/
Docsify	文檔部署	//docsify.js.org/#/
Hutool	服務集成	//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:8888即可訪問對應文檔

參考文檔

[1] SpringBoot整合Docsify生成網站文檔-每天學Java-騰訊雲社區

Tags: JAVA springboot