当前位置：首页 > news >正文

Spring Boot 项目文档编写工具推荐

news 2025/6/26 10:23:41

在 Spring Boot 项目开发中，推荐使用以下工具编写文档，根据需求选择合适方案：

一、API 文档工具（首选）

1. Swagger / OpenAPI

推荐库：springdoc-openapi（支持 OpenAPI 3）
优点：
- 自动生成可视化 API 文档
- 支持在线调试接口
- 注解驱动（与代码同步更新）

步骤：

添加依赖：

xml

复制

下载

运行

<dependency><groupId>org.springdoc</groupId><artifactId>springdoc-openapi-starter-webmvc-ui</artifactId><version>2.5.0</version> <!-- 检查最新版本 -->
</dependency>

启动项目，访问 http://localhost:8080/swagger-ui.html

在 Controller 中使用注解描述接口：

java

复制

下载

@Operation(summary = "创建用户")
@PostMapping("/users")
public User createUser(@RequestBody User user) { ... }

2. Spring REST Docs

优点：
- 通过单元测试生成文档，保证准确性
- 输出 Asciidoctor/Markdown 格式
- 适合需要严谨文档的项目

步骤：

添加测试依赖：

xml

复制

下载

运行

<dependency><groupId>org.springframework.restdocs</groupId><artifactId>spring-restdocs-mockmvc</artifactId><scope>test</scope>
</dependency>

编写测试用例生成文档片段：

java

复制

下载

@Test
void getUserExample() throws Exception {mockMvc.perform(get("/users/1")).andExpect(status().isOk()).andDo(document("get-user", pathParameters(parameterWithName("id").description("用户ID"))));
}

组合片段生成完整文档（支持 HTML/PDF）。

二、项目综合文档

1. Markdown + 静态站点生成器

工具组合：
- 编写：Typora / VS Code
- 生成静态站点：MkDocs / Docsify / Docusaurus
优点：
- 轻量级，适合需求文档、设计说明
- 支持版本控制（Git 友好）

示例结构：

markdown

复制

下载

## 用户模块
- **功能**：管理用户信息
- **接口**：`GET /users/{id}` - 获取用户详情

2. Confluence

适用场景：
- 团队协作文档
- 需求管理、知识沉淀
优点：集成 Jira、权限管理完善

三、数据库文档

工具：Screw（轻量级数据库文档生成器）

步骤：

添加依赖：

xml

复制

下载

运行

<dependency><groupId>cn.smallbun.screw</groupId><artifactId>screw-core</artifactId><version>1.0.8</version>
</dependency>

配置生成器：

java

复制

下载

new SchemaCrawlerEngine(config).generate(); // 输出 HTML/Word/Markdown

四、代码注释文档

工具：Javadoc + Maven Javadoc Plugin

使用：

java

复制

下载

/*** 创建用户* @param user 用户对象（必填）* @return 创建后的用户*/
public User create(User user) { ... }

生成命令：mvn javadoc:javadoc

选择建议

场景	推荐工具
实时 API 文档与调试	Swagger (springdoc)
严格规范的 API 文档	Spring REST Docs
项目设计文档/需求说明	Markdown + MkDocs
团队知识库	Confluence
数据库表结构文档	Screw
Java 代码注释文档	Javadoc