需求分析
- 文檔可以和項目一起進行版本管理
- 文檔可以在線訪問
- 文檔可以與springboot項目集成，不需要分開部署
- MarkDown支持
- 文檔跟隨，打包
jar也可以訪問
技術選型
對於網上已有的方案，大致分爲如下幾種
- 將文檔部署在
resource靜態資源目錄下，用模板渲染訪問。\(^{[1]}\) - 分離部署，打包
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:8888即可訪問對應文檔
