Ubuntu Java怎样生成API文档

Ubuntu Java生成API文档的常用方法

一、使用Javadoc工具（官方标准方式）

Javadoc是Java自带的工具，可从源代码的文档注释（/** … */）中提取信息，生成符合Java规范的HTML格式API文档，是最基础的离线文档生成方式。

1. 准备文档注释

在Java类、方法、字段的声明前，使用/** ... */格式编写注释，配合@param（参数说明）、@return（返回值说明）、@throws（异常说明）等标签增强文档完整性。示例如下：

/** * 计算两个整数的和 ** @param a 第一个整数 * @param b 第二个整数 * @return 两个整数的和 * @throws IllegalArgumentException 如果参数为负数 */public int add(int a, int b) {if (a < 0 || b < 0) {throw new IllegalArgumentException("参数不能为负数");}return a + b;}

2. 执行Javadoc命令

打开Ubuntu终端，进入项目根目录，执行以下命令：

javadoc -d docs -sourcepath src -subpackages com.example.demo

• -d docs：指定生成的文档存放目录（如docs文件夹）；
• -sourcepath src：指定源代码目录（如src文件夹）；
• -subpackages com.example.demo：递归扫描指定包下的所有类（支持多包扫描）。

3. 查看生成的文档

命令执行完成后，在终端输入以下命令用浏览器打开生成的index.html文件：

xdg-open docs/index.html

即可查看包含类、方法、参数等详细信息的API文档。

二、使用Swagger生成交互式API文档（适合Web项目）

Swagger（现称OpenAPI）是一款用于描述、生成、测试API的工具，适合Spring Boot等Web项目，可生成交互式的HTML/JSON/YAML文档，支持在线测试接口。

1. 环境准备

确保系统已安装Java（≥11）和Maven（≥3.6），若未安装可通过以下命令安装：

sudo apt updatesudo apt install openjdk-11-jdk maven

2. 添加Swagger依赖

以Spring Boot项目为例，在pom.xml中添加Swagger依赖（推荐使用springfox-boot-starter，简化配置）：

<dependencies><dependency><groupId>org.springfox</groupId><artifactId>springfox-boot-starter</artifactId><version>3.0.0</version></dependency></dependencies>

3. 配置Swagger

创建一个配置类（如SwaggerConfig.java），启用Swagger并指定扫描的包路径：

import org.springframework.context.annotation.Bean;import org.springframework.context.annotation.Configuration;import springfox.documentation.builders.PathSelectors;import springfox.documentation.builders.RequestHandlerSelectors;import springfox.documentation.spi.DocumentationType;import springfox.documentation.spring.web.plugins.Docket;@Configurationpublic class SwaggerConfig {@Beanpublic Docket api() {return new Docket(DocumentationType.SWAGGER_2).select().apis(RequestHandlerSelectors.basePackage("com.example.demo.controller")) // 替换为你的控制器包路径.paths(PathSelectors.any()).build();}}

4. 启动应用并访问文档

启动Spring Boot应用（如./mvnw spring-boot:run），在浏览器中访问以下URL查看Swagger UI：

http://localhost:8080/swagger-ui/index.html

即可看到自动生成的API文档，支持在线测试接口（如发送GET/POST请求、查看响应结果）。

三、IDE集成方式（辅助开发调试）

若使用IntelliJ IDEA或Eclipse等IDE，可通过内置工具快速生成Javadoc文档，适合本地开发调试。

1. IntelliJ IDEA生成Javadoc

• 选中项目或包，点击顶部菜单栏的Tools → Generate JavaDoc…；
• 在弹出的窗口中，设置Output directory（输出目录，如docs）、Scope（范围，如All in project）；
• 点击OK，IDE会自动生成HTML格式的API文档。

2. Eclipse生成Javadoc

• 右键点击项目或包，选择Export…；
• 在弹出的窗口中，展开Java节点，选择Javadoc，点击Next；
• 配置Destination（输出目录）、Javadoc command（Javadoc工具路径，默认自动检测）；
• 点击Finish，生成API文档。