SpringBoot項目集成Smart-Doc的實戰(zhàn)指南
更新時間：2025年10月24日 08:49:28 作者：Micro麥可樂
Smart-Doc是一款強大的基于Java的API文檔生成工具,它通過對接口源代碼進行分析來生成全面而準確的文檔,完全不需要對代碼進行任何注入,下面我們看看如何在SpringBoot項目中集成Smart-Doc吧
為什么我放棄了SpringDoc OpenAPI
在我們開發(fā) Spring Boot 項目中，相信很多小伙伴最初都是選擇 SpringDoc OpenAPI (Swagger3) 來生成接口文檔。博主之前也寫了一篇整合SpringDoc OpenAPI的文章，感興趣的可以查閱 SpringBoot3整合SpringDoc OpenAPI生成接口文檔的詳細過程
SpringDoc OpenAPI 它可以通過注解自動生成交互式文檔（Swagger UI），你是不是覺的也挺方便挺好的，實際上當項目規(guī)模逐漸增大、功能需求不斷更新后，你就會慢慢發(fā)現(xiàn)以下這類問題：
1、代碼侵入性強
需要大量 @Schema、@Operation、@ApiResponse 等注解來完善文檔，增加代碼耦合和維護負擔！
常見的注解示例如下：
當業(yè)務功能有所調(diào)整，我們也需要一并對注解進行修改
import com.toher.springdoc.bean.User;
import io.swagger.v3.oas.annotations.Operation;
import io.swagger.v3.oas.annotations.Parameter;
import io.swagger.v3.oas.annotations.media.Content;
import io.swagger.v3.oas.annotations.media.Schema;
import io.swagger.v3.oas.annotations.responses.ApiResponse;
import io.swagger.v3.oas.annotations.responses.ApiResponses;
import org.springframework.web.bind.annotation.*;
/**
* @Author 麥可樂
* @Date 2025/10/20 11:17 AM
* @Version 1.0
*/
@RestController
@RequestMapping("/api/users")
public class UserController {
@Operation(summary = "獲取用戶信息接口", description = "通過用戶ID獲取用戶信息")
@ApiResponses(value = {
@ApiResponse(responseCode = "200", description = "用戶信息",
content = {@Content(mediaType = "application/json",
schema = @Schema(implementation = User.class))}),
@ApiResponse(responseCode = "404", description = "無法獲取用戶信息")
})
@GetMapping("/{id}")
public User getUserById(@Parameter(description = "用戶ID") @PathVariable Long id) {
//模擬數(shù)據(jù)庫獲取用戶
User user = new User();
user.setId(1L);
user.setName("張三");
user.setEmail("zhansan@qq.com");
return user;
}
}
2、運行依賴問題
目前大多數(shù)企業(yè)都是前后端協(xié)同開發(fā)的，而SpringDoc OpenAPI 生成接口文檔依賴項目運行環(huán)境（即需要 Spring 啟動），意味著文檔無法離線生成，CI/CD 集成麻煩。
3、多模塊支持問題
很多時候我們的項目都是基于多模塊的，如一個 SpringBoot 項目中包含了前端API模塊和后端API模塊，那么我們分別就需要啟動前端API服務和后端API服務，SpringDoc 很難整合多個模塊接口，需要手動聚合
Smart-Doc 的出現(xiàn)：讓接口文檔真正無侵入
直到博主發(fā)現(xiàn)了Smart-Doc，它最大的特點是——無需啟動項目、無需注解，通過靜態(tài)源碼分析生成接口文檔，官方文檔地址：https://smart-doc-group.github.io/zh/
Smart-Doc核心特點
- 零侵入：完全基于注釋信息生成文檔，實現(xiàn)代碼零侵入
- 接口多樣性：支持為Java RESTful API、Java WebSocket、Apache Dubbo RPC和gRPC接口生成文檔
- 框架多樣性：支持 Spring Boot、JAX-RS、Solon等多種框架
- 文檔豐富：支持生成 HTML、Asciidoc、Markdown、OpenAPI、Swagger、Postman、Word 等多種格式的文檔
- 支持拓展：支持用戶使用 Java SPI 對支持框架進行擴展
- 文檔協(xié)作管理：Smart-Doc 和 Torna 結(jié)合形成行業(yè)領先的文檔解決方案
SpringBoot快速整合smart-doc
為了讓大家迅速掌握smart-doc，我們先從最簡單的單模塊 Spring Boot 項目開始
項目結(jié)構(gòu)示例
小伙伴們自行構(gòu)建SpringBoot項目，博主的項目結(jié)構(gòu)如下：
添加 Maven 插件
在 pom.xml 中加入 Smart-Doc 插件配置
<?xml version="1.0" encoding="UTF-8"?>
<project xmlns="http://maven.apache.org/POM/4.0.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 https://maven.apache.org/xsd/maven-4.0.0.xsd">
<modelVersion>4.0.0</modelVersion>
<parent>
<groupId>org.springframework.boot</groupId>
<artifactId>spring-boot-starter-parent</artifactId>
<version>3.5.7</version>
<relativePath/> <!-- lookup parent from repository -->
</parent>
<groupId>com.toher</groupId>
<artifactId>smart-doc-demo</artifactId>
<version>0.0.1-SNAPSHOT</version>
<name>smart-doc-demo</name>
<description>smart-doc-demo</description>
<properties>
<java.version>17</java.version>
</properties>
<dependencies>
<dependency>
<groupId>org.springframework.boot</groupId>
<artifactId>spring-boot-starter-web</artifactId>
</dependency>
<dependency>
<groupId>org.springframework.boot</groupId>
<artifactId>spring-boot-starter-test</artifactId>
<scope>test</scope>
</dependency>
<dependency>
<groupId>org.projectlombok</groupId>
<artifactId>lombok</artifactId>
</dependency>
</dependencies>
<build>
<plugins>
<plugin>
<groupId>org.springframework.boot</groupId>
<artifactId>spring-boot-maven-plugin</artifactId>
</plugin>
<plugin>
<groupId>com.ly.smart-doc</groupId>
<artifactId>smart-doc-maven-plugin</artifactId>
<version>3.1.1</version>
<configuration>
<configFile>./src/main/resources/smart-doc.json</configFile>
<projectName>${project.description}</projectName>
</configuration>
<executions>
<execution>
<!--如果不需要在執(zhí)行編譯時啟動smart-doc，則將phase注釋掉-->
<phase>compile</phase>
<goals>
<!--smart-doc提供了html、openapi、markdown等goal，可按需配置-->
<goal>html</goal>
</goals>
</execution>
</executions>
</plugin>
</plugins>
</build>
</project>
添加Smart-Doc配置文件
本文主要給大家演示如何快速接入Smart-Doc，更多配置文件項說明請參考官方文檔 https://smart-doc-group.github.io/zh/guide/advanced/config
在resources目錄下創(chuàng)建smart-doc.json
{
"outPath": "src/main/resources/static/doc",
"projectName": "SmartDoc Demo",
"allInOne": true,
"serverUrl": "http://localhost:8080",
"packageFilters": "com.toher.smartdocdemo.controller",
"sourceCodePaths": [
{
"path": "src/main/java",
"desc": "Main Source"
}
]
}
編寫實體類User
/**
* 用戶實體類
*
* @Author: micro麥可樂
* @Date: 2025/10/20 18:59
*
**/
@Data
@AllArgsConstructor
public class User {
/**
* 用戶ID主鍵
*/
private Long id;
/**
* 用戶名稱
*/
private String name;
}
編寫Controller
/**
* 用戶管理接口
* @Author: micro麥可樂
* @Date: 2025/10/20 18:59
*/
@RestController
@RequestMapping("/users")
public class UserController {
/**
* 獲取用戶列表
* @return 返回用戶列表
*/
@GetMapping
public List<User> list() {
List<User> list = new ArrayList<>();
list.add(new User(1L, "Alice"));
list.add(new User(2L, "Bob"));
return list;
}
/**
* 創(chuàng)建用戶
* @param user
* @return 返回創(chuàng)建用戶
*/
@PostMapping
public User create(@RequestBody User user) {
user.setId(3L);
return user;
}
/**
* 根據(jù)ID獲取用戶信息
* @param id 用戶ID
* @return 返回用戶對象
*/
@GetMapping("/{id}")
public User getUserById(@PathVariable Long id) {
return new User(id, "張三");
}
}
運行生成文檔
生成文檔命令
mvn smart-doc:html
通過IDEA maven生成
文檔最終生成效果
結(jié)語
通過本文的講解以及快速集成案例，相信小伙伴們已經(jīng)掌握了在 SpringBoot 項目中整合smart-doc的方法。smart-doc 的零侵入特性讓我們的代碼更加整潔，基于注釋的文檔生成方式也更符合開發(fā)者的習慣。趕緊在項目中嘗試使用smart-doc，體驗它帶來的便捷和高效吧！
以上就是SpringBoot項目集成Smart-Doc的實戰(zhàn)指南的詳細內(nèi)容，更多關(guān)于SpringBoot集成Smart-Doc的資料請關(guān)注腳本之家其它相關(guān)文章！
相關(guān)文章
詳解SpringBoot中@PostMapping注解的用法
在SpringBoot中，我們經(jīng)常需要編寫RESTful Web服務，以便于客戶端與服務器之間的通信，@PostMapping注解可以讓我們更方便地編寫POST請求處理方法，在本文中，我們將介紹@PostMapping注解的作用、原理，以及如何在SpringBoot應用程序中使用它2023-06-06
這篇文章主要介紹了Java枚舉類型在switch語句正確使用方法詳解,文中通過示例代碼介紹的非常詳細，對大家的學習或者工作具有一定的參考學習價值,需要的朋友可以參考下2020-07-07
常見的編碼有ASCII碼、Unicode編碼。最簡單的編碼是直接給每個字符指定一個若干字節(jié)表示的整數(shù)，復雜一點的編碼就需要根據(jù)已有的編碼推算出來。本文將為大家詳細講講Java重點加密與安全，感興趣的可以了解一下2022-07-07
在使用IDEA環(huán)境搭建MyBatis框架時,可能會因為依賴包版本過低導致兼容性問題,本文就來介紹一下MyBatis框架搭建時依賴包引入異常的問題解決,感興趣的可以來了解一下2024-10-10
MyBatis如何實現(xiàn)多表查詢（多對一、一對多）
這篇文章主要給大家介紹了關(guān)于MyBatis如何實現(xiàn)多表查詢（多對一、一對多）的相關(guān)資料，文中通過示例代碼介紹的非常詳細，對大家的學習或者工作具有一定的參考學習價值，需要的朋友們下面隨著小編來一起學習學習吧2021-05-05
這篇文章主要介紹了springboot默認掃描的路徑方式，具有很好的參考價值，希望對大家有所幫助。如有錯誤或未考慮完全的地方，望不吝賜教2023-07-07
這篇文章主要介紹了Java使用DualPivotQuicksort排序，喜歡算法的同學一定要看一下2021-04-04
Java 并發(fā)編程ArrayBlockingQueue的實現(xiàn)
這篇文章主要介紹了Java 并發(fā)編程ArrayBlockingQueue的實現(xiàn),文中通過示例代碼介紹的非常詳細，對大家的學習或者工作具有一定的參考學習價值，需要的朋友們下面隨著小編來一起學習學習吧2021-02-02
這篇文章主要給大家總結(jié)介紹了關(guān)于Mybatis查詢語句結(jié)果集的相關(guān)資料，文中通過示例代碼介紹的非常詳細，對大家的學習或者工作具有一定的參考學習價值，需要的朋友們下面隨著小編來一起學習學習吧2018-08-08
本文主要介紹了SpringBoot中cache使用的實現(xiàn)示例,文中通過示例代碼介紹的非常詳細,對大家的學習或者工作具有一定的參考學習價值,需要的朋友們下面隨著小編來一起學習學習吧2025-10-10