如何在Debian上构建Java项目的文档

在 Debian 上构建 Java 项目文档的实用指南

一 准备环境

• 安装 JDK（推荐 OpenJDK 11/17）：sudo apt update && sudo apt install openjdk-17-jdk（或 openjdk-11-jdk）。
• 可选：设置 JAVA_HOME，例如在 ~/.bashrc 中添加：export JAVA_HOME=/usr/lib/jvm/java-17-openjdk-amd64，然后 source ~/.bashrc。
• 安装构建工具（按项目需要）：sudo apt install maven 或 sudo apt install gradle。
• 安装文档工具：
  • API 文档生成器 Javadoc（随 JDK 提供）；
  • 跨语言文档工具 Doxygen（支持 Java，Debian 上可安装 doxygen 与 graphviz 以生成图表）；
  • 接口文档 Swagger/OpenAPI（Spring Boot 项目常用，运行时通过 UI 查看）。

二 使用 Javadoc 生成 API 文档

• 项目内直接生成（Maven）：在项目根目录执行 mvn javadoc:javadoc，HTML 输出默认在 target/site/apidocs/index.html。
• 项目内直接生成（Gradle）：执行 gradle javadoc，HTML 输出默认在 build/docs/javadoc/index.html。
• 系统命令行生成（通用，适合 Ant 或无构建工具项目）：
  1. 安装 Ant（可选）：sudo apt install ant；
  2. 在源码根目录准备 build.xml，示例：
     
     
     
     
     
     
     
  3. 运行：ant docs，文档生成至 docs/。
• 提示：Javadoc 对中文和编码敏感，建议在调用前设置环境变量：export JAVA_TOOL_OPTIONS=“-Dfile.encoding=UTF-8”。

三 使用 Doxygen 生成代码文档（含图表）

• 安装：sudo apt install doxygen graphviz（graphviz 用于生成调用/继承图）。
• 初始化配置：在项目根目录执行 doxygen -g 生成 Doxyfile。
• 关键配置示例（编辑 Doxyfile）：
  • PROJECT_NAME = “My Project”
  • INPUT = ./src；RECURSIVE = YES
  • OUTPUT_DIRECTORY = ./docs
  • GENERATE_HTML = YES；GENERATE_LATEX = NO
  • HAVE_DOT = YES（启用 Graphviz 图形）
• 生成文档：doxygen Doxyfile，HTML 文档位于 ./docs/html/index.html。
• 适用场景：需要同时生成 Java/C++/Python 等多语言代码文档、类图/调用图、以及更丰富的站点化输出时，Doxygen 是通用选择。

四 使用 Swagger 生成在线接口文档（Spring Boot 示例）

• 安装环境：sudo apt install openjdk-11-jdk maven。
• 添加依赖（Maven，Springfox 2.x 示例）：
  
  
  io.springfox
  springfox-swagger2
  2.9.2
  
  
  io.springfox
  springfox-swagger-ui
  2.9.2
  
  
• 配置（启用 Swagger 2）：
  @Configuration
  @EnableSwagger2
  public class SwaggerConfig {
  @Bean
  public Docket api() {
  return new Docket(DocumentationType.SWAGGER_2)
  .select()
  .apis(RequestHandlerSelectors.basePackage(“com.example.controller”))
  .paths(PathSelectors.any())
  .build();
  }
  }
• 运行与访问：
  • 启动：mvn spring-boot:run（或 java -jar target/xxx.jar）；
  • 浏览器访问：http://localhost:8080/swagger-ui.html（端口以实际配置为准）。
• 说明：Springfox 2.x 与 Spring Boot 2.x 搭配常见；若使用 Spring Boot 3，建议迁移到 SpringDoc OpenAPI（springdoc-openapi-starter-webmvc-ui） 以获得更好的兼容性。

五 实用建议

• 选择策略：
  • 仅需 Java API 文档：优先用 Javadoc（Maven/Gradle 一键生成，集成发布流程简单）；
  • 需要 跨语言/图表/站点化：选择 Doxygen；
  • REST API 在线文档与调试：使用 Swagger/OpenAPI（运行时查看与测试）。
• 输出与发布：将生成的 HTML 目录（如 target/site/apidocs、./docs/html）加入静态站点或通过 Nginx 发布；CI 中可添加 mvn javadoc:javadoc 或 doxygen 步骤并归档产物。
• 质量与规范：为代码添加规范的注释（Javadoc 风格或 Doxygen 风格），并在 CI 中开启文档检查/覆盖率，避免文档过期。