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 update
sudo 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;

@Configuration
public class SwaggerConfig {
    @Bean
    public 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文档。