Java如何自動(dòng)生成api文檔

更新時(shí)間：2025年02月13日 08:30:23 作者：五行星辰

在?Java?開發(fā)中,自動(dòng)生成?API?文檔是一項(xiàng)非常實(shí)用的功能,這篇為大家介紹了幾種常見的?Java?自動(dòng)生成?API?文檔的方式,需要的可以參考一下

1. 使用 Javadoc

Javadoc 是 Java 自帶的工具，它可以從 Java 源代碼中的注釋生成 API 文檔。

代碼注釋規(guī)范

在 Java 代碼中，使用特定格式的注釋來描述類、方法、參數(shù)等信息。例如：

/**
 * 這是一個(gè)示例類，用于演示 Javadoc 的使用。
 *
 * @author 開發(fā)者姓名
 * @version 1.0
 */
public class ExampleClass {
    /**
     * 這是一個(gè)示例方法，用于計(jì)算兩個(gè)整數(shù)的和。
     *
     * @param a 第一個(gè)整數(shù)
     * @param b 第二個(gè)整數(shù)
     * @return 兩個(gè)整數(shù)的和
     */
    public int add(int a, int b) {
        return a + b;
    }
}

上述代碼中，類注釋使用 /** ... */ 包裹，包含了類的描述、作者和版本信息。方法注釋同樣使用 /** ... */ 包裹，包含了方法的描述、參數(shù)說明和返回值說明。

生成文檔

在命令行中，進(jìn)入包含 Java 源代碼的目錄，執(zhí)行以下命令來生成 Javadoc 文檔：

javadoc -d doc ExampleClass.java

其中，-d 選項(xiàng)指定生成文檔的輸出目錄，doc 是輸出目錄的名稱，ExampleClass.java 是要生成文檔的 Java 源文件。如果有多個(gè)源文件，可以依次列出它們，或者使用通配符 *.java 表示當(dāng)前目錄下的所有 Java 文件。

查看文檔

生成的文檔會(huì)存放在指定的輸出目錄中，打開該目錄下的 index.html 文件，就可以在瀏覽器中查看生成的 API 文檔。

2. 使用 Swagger

Swagger 是一個(gè)強(qiáng)大的 API 文檔生成工具，它可以自動(dòng)生成 RESTful API 的文檔，并且支持多種語言，包括 Java。

添加依賴

如果你使用 Maven 項(xiàng)目，在 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

創(chuàng)建一個(gè)配置類來啟用 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 {
    @Bean
    public Docket api() {
        return new Docket(DocumentationType.SWAGGER_2)
               .select()
               .apis(RequestHandlerSelectors.basePackage("com.example.controller"))
               .paths(PathSelectors.any())
               .build();
    }
}

上述代碼中，@Configuration 注解表示這是一個(gè)配置類，@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 = "這是一個(gè)示例 API 文檔")
public class ExampleController {
    @GetMapping("/hello")
    @ApiOperation(value = "獲取問候語", notes = "返回一個(gè)簡單的問候語")
    public String hello() {
        return "Hello, World!";
    }
}

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

查看文檔

啟動(dòng) Spring Boot 應(yīng)用程序后，訪問 http://localhost:8080/swagger-ui.html（端口號(hào)根據(jù)實(shí)際情況修改），就可以在瀏覽器中查看生成的 API 文檔。

3. 使用 Spring REST Docs

Spring REST Docs 是 Spring 官方提供的用于生成 RESTful API 文檔的工具，它結(jié)合了測試用例來生成文檔，確保文檔的準(zhǔn)確性。

添加依賴

如果你使用 Maven 項(xiàng)目，在 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 {
    @Autowired
    private MockMvc mockMvc;
 
    @Test
    public void shouldReturnDefaultMessage() throws Exception {
        this.mockMvc.perform(get("/api/hello"))
               .andExpect(status().isOk())
               .andDo(document("hello",
                        preprocessRequest(prettyPrint()),
                        preprocessResponse(prettyPrint())));
    }
}

上述代碼中，使用 @AutoConfigureRestDocs 注解自動(dòng)配置 REST Docs，在測試用例中使用 document 方法生成文檔片段。

集成文檔

在 src/main/asciidoc 目錄下創(chuàng)建 index.adoc 文件，將生成的文檔片段集成到 AsciiDoc 文檔中：

= 示例 API 文檔

== 問候語 API

include::{snippets}/hello/curl-request.adoc[]
include::{snippets}/hello/http-request.adoc[]
include::{snippets}/hello/http-response.adoc[]

生成 HTML 文檔

使用 Asciidoctor 或其他工具將 AsciiDoc 文檔轉(zhuǎn)換為 HTML 文檔：