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

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

一、API 文档工具（首选）

1. Swagger / OpenAPI

• 推荐库：springdoc-openapi（支持 OpenAPI 3）

• 优点：

  • 自动生成可视化 API 文档

  • 支持在线调试接口

  • 注解驱动（与代码同步更新）

• 步骤：

  1. 添加依赖：

     xml

     复制

     下载

     运行

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

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

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

     java

     复制

     下载

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

2. Spring REST Docs

• 优点：

  • 通过单元测试生成文档，保证准确性

  • 输出 Asciidoctor/Markdown 格式

  • 适合需要严谨文档的项目

• 步骤：

  1. 添加测试依赖：

     xml

     复制

     下载

     运行

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

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

     java

     复制

     下载

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

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

二、项目综合文档

1. Markdown + 静态站点生成器

• 工具组合：

  • 编写：Typora / VS Code

  • 生成静态站点：MkDocs / Docsify / Docusaurus

• 优点：

  • 轻量级，适合需求文档、设计说明

  • 支持版本控制（Git 友好）

• 示例结构：

  markdown

  复制

  下载

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

2. Confluence

• 适用场景：

  • 团队协作文档

  • 需求管理、知识沉淀

• 优点：集成 Jira、权限管理完善

三、数据库文档

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

• 步骤：

  1. 添加依赖：

     xml

     复制

     下载

     运行

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

  2. 配置生成器：

     java

     复制

     下载

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

四、代码注释文档

• 工具：Javadoc + Maven Javadoc Plugin

• 使用：

  java

  复制

  下载

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

• 生成命令：mvn javadoc:javadoc

选择建议

提示：大型项目可组合使用，如：

• 用 Swagger 快速调试 + Spring REST Docs 生成交付文档

• Markdown 写设计文档 + Screw 生成数据库说明