Java自动生成api文档

在 Java 开发中，自动生成 API 文档是一项非常实用的功能，它能帮助开发者快速了解项目中的类、方法、参数等信息。以下为你介绍几种常见的 Java 自动生成 API 文档的方式：

1. 使用 Javadoc

Javadoc 是 Java 自带的工具，它可以从 Java 源代码中的注释生成 API 文档。

代码注释规范

在 Java 代码中，使用特定格式的注释来描述类、方法、参数等信息。例如：

/*** 这是一个示例类，用于演示 Javadoc 的使用。** @author 开发者姓名* @version 1.0*/
public class ExampleClass {/*** 这是一个示例方法，用于计算两个整数的和。** @param a 第一个整数* @param b 第二个整数* @return 两个整数的和*/public int add(int a, int b) {return a + b;}
}

上述代码中，类注释使用 /** ... */ 包裹，包含了类的描述、作者和版本信息。方法注释同样使用 /** ... */ 包裹，包含了方法的描述、参数说明和返回值说明。

生成文档

在命令行中，进入包含 Java 源代码的目录，执行以下命令来生成 Javadoc 文档：

javadoc -d doc ExampleClass.java

其中，-d 选项指定生成文档的输出目录，doc 是输出目录的名称，ExampleClass.java 是要生成文档的 Java 源文件。如果有多个源文件，可以依次列出它们，或者使用通配符 *.java 表示当前目录下的所有 Java 文件。

查看文档

生成的文档会存放在指定的输出目录中，打开该目录下的 index.html 文件，就可以在浏览器中查看生成的 API 文档。

2. 使用 Swagger

Swagger 是一个强大的 API 文档生成工具，它可以自动生成 RESTful API 的文档，并且支持多种语言，包括 Java。

添加依赖

如果你使用 Maven 项目，在 pom.xml 中添加以下依赖：

<dependencies><!-- Swagger API 注解 --><dependency><groupId>io.springfox</groupId><artifactId>springfox-swagger2</artifactId><version>2.9.2</version></dependency><!-- Swagger UI --><dependency><groupId>io.springfox</groupId><artifactId>springfox-swagger-ui</artifactId><version>2.9.2</version></dependency>
</dependencies>

配置 Swagger

创建一个配置类来启用 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;
import springfox.documentation.swagger2.annotations.EnableSwagger2;@Configuration
@EnableSwagger2
public class SwaggerConfig {@Beanpublic Docket api() {return new Docket(DocumentationType.SWAGGER_2).select().apis(RequestHandlerSelectors.basePackage("com.example.controller")).paths(PathSelectors.any()).build();}
}

上述代码中，@Configuration 注解表示这是一个配置类，@EnableSwagger2 注解启用 Swagger。Docket 是 Swagger 的核心配置类，通过 select() 方法选择要生成文档的控制器类和请求路径。

添加 API 注解

在控制器类和方法上添加 Swagger 注解来描述 API 信息：

import io.swagger.annotations.Api;
import io.swagger.annotations.ApiOperation;
import org.springframework.web.bind.annotation.GetMapping;
import org.springframework.web.bind.annotation.RequestMapping;
import org.springframework.web.bind.annotation.RestController;@RestController
@RequestMapping("/api")
@Api(value = "示例 API", description = "这是一个示例 API 文档")
public class ExampleController {@GetMapping("/hello")@ApiOperation(value = "获取问候语", notes = "返回一个简单的问候语")public String hello() {return "Hello, World!";}
}

上述代码中，@Api 注解用于描述控制器类的信息，@ApiOperation 注解用于描述方法的信息。

查看文档

启动 Spring Boot 应用程序后，访问 http://localhost:8080/swagger-ui.html（端口号根据实际情况修改），就可以在浏览器中查看生成的 API 文档。

3. 使用 Spring REST Docs

Spring REST Docs 是 Spring 官方提供的用于生成 RESTful API 文档的工具，它结合了测试用例来生成文档，确保文档的准确性。

添加依赖

如果你使用 Maven 项目，在 pom.xml 中添加以下依赖：

<dependencies><dependency><groupId>org.springframework.restdocs</groupId><artifactId>spring-restdocs-mockmvc</artifactId><version>2.0.6.RELEASE</version><scope>test</scope></dependency>
</dependencies>

编写测试用例并生成文档

import org.junit.jupiter.api.Test;
import org.springframework.beans.factory.annotation.Autowired;
import org.springframework.boot.test.autoconfigure.restdocs.AutoConfigureRestDocs;
import org.springframework.boot.test.autoconfigure.web.servlet.WebMvcTest;
import org.springframework.test.web.servlet.MockMvc;import static org.springframework.restdocs.mockmvc.MockMvcRestDocumentation.document;
import static org.springframework.restdocs.operation.preprocess.Preprocessors.*;
import static org.springframework.test.web.servlet.request.MockMvcRequestBuilders.get;
import static org.springframework.test.web.servlet.result.MockMvcResultMatchers.status;@WebMvcTest(ExampleController.class)
@AutoConfigureRestDocs(outputDir = "target/generated-snippets")
public class ExampleControllerDocumentation {@Autowiredprivate MockMvc mockMvc;@Testpublic void shouldReturnDefaultMessage() throws Exception {this.mockMvc.perform(get("/api/hello")).andExpect(status().isOk()).andDo(document("hello",preprocessRequest(prettyPrint()),preprocessResponse(prettyPrint())));}
}

上述代码中，使用 @AutoConfigureRestDocs 注解自动配置 REST Docs，在测试用例中使用 document 方法生成文档片段。

集成文档

在 src/main/asciidoc 目录下创建 index.adoc 文件，将生成的文档片段集成到 AsciiDoc 文档中：

= 示例 API 文档== 问候语 APIinclude::{snippets}/hello/curl-request.adoc[]
include::{snippets}/hello/http-request.adoc[]
include::{snippets}/hello/http-response.adoc[]

生成 HTML 文档

使用 Asciidoctor 或其他工具将 AsciiDoc 文档转换为 HTML 文档：

asciidoctor -b html5 -a stylesheet=styles.css src/main/asciidoc/index.adoc -o target/generated-docs/index.html

通过以上几种方式，你可以根据项目的需求和特点选择合适的工具来自动生成 Java API 文档。