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文档。

声明：本文内容由网友自发贡献，本站不承担相应法律责任。对本内容有异议或投诉，请联系2913721942#qq.com核实处理，我们将尽快回复您，谢谢合作！