Java里如何搭建API文档生成工具环境

在Java项目开发中，API文档是前后端协作、接口对接的重要参考依据，手动维护文档不仅耗时耗力，还容易出现文档与实际接口不一致的问题。使用自动化的API文档生成工具可以很好地解决这个痛点，其中Swagger是Java生态中应用最广泛的API文档工具之一，下面以Spring Boot项目整合Swagger为例，讲解完整的搭建流程。

一、环境准备

首先确保本地已经安装好JDK 8及以上版本，并且已经搭建好Maven或Gradle构建工具，本文以Maven构建的Spring Boot 2.x项目为例进行演示，项目的基础依赖已经包含Spring Web相关组件。

二、引入Swagger依赖

在项目的pom.xml文件中添加Swagger的核心依赖，这里使用springfox-swagger2和springfox-swagger-ui两个依赖，前者是Swagger的核心功能包，后者是Swagger的UI界面包。

<!-- Swagger核心依赖 -->
<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>

如果是Gradle项目，则在build.gradle文件中添加如下依赖：

implementation 'io.springfox:springfox-swagger2:2.9.2'
implementation 'io.springfox:springfox-swagger-ui:2.9.2'

三、编写Swagger配置类

依赖引入完成后，需要创建Swagger的配置类，对文档的基本信息、扫描范围、接口过滤规则等进行配置。配置类需要添加@Configuration注解标识为配置类，同时添加@EnableSwagger2注解开启Swagger功能。

import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import springfox.documentation.builders.ApiInfoBuilder;
import springfox.documentation.builders.PathSelectors;
import springfox.documentation.builders.RequestHandlerSelectors;
import springfox.documentation.service.ApiInfo;
import springfox.documentation.service.Contact;
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 createRestApi() {
        return new Docket(DocumentationType.SWAGGER_2)
                // 配置API文档的基本信息
                .apiInfo(apiInfo())
                // 配置接口扫描规则
                .select()
                // 扫描指定包下的接口，替换为自己的controller包路径
                .apis(RequestHandlerSelectors.basePackage("com.example.demo.controller"))
                // 过滤路径，这里表示扫描所有路径
                .paths(PathSelectors.any())
                .build();
    }

    private ApiInfo apiInfo() {
        return new ApiInfoBuilder()
                // 文档标题
                .title("示例项目API文档")
                // 文档描述
                .description("这是Spring Boot整合Swagger生成的API文档，包含项目所有接口说明")
                // 联系人信息
                .contact(new Contact("开发者", "https://ipipp.com", "test@ipipp.com"))
                // 文档版本
                .version("1.0.0")
                .build();
    }
}

四、配置项解析

上面的配置类中包含多个核心配置项，下面逐一解析其作用：

• DocumentationType.SWAGGER_2：指定使用的Swagger版本，这里选择Swagger2版本。
• apiInfo：配置API文档的基本元信息，包括标题、描述、联系人、版本等，这些信息会显示在Swagger UI的首页。
• RequestHandlerSelectors.basePackage：指定扫描的Controller包路径，Swagger只会生成该包下接口的文档，避免扫描到无关的类。
• PathSelectors.any()：配置接口路径的过滤规则，any()表示匹配所有路径，也可以根据需求使用regex()自定义正则匹配规则。
• @EnableSwagger2：该注解用于开启Swagger的自动配置，只有添加该注解后，Swagger才会生效。

五、验证环境是否搭建成功

完成上述配置后，启动Spring Boot项目，在浏览器中访问http://127.0.0.1:8080/swagger-ui.html，如果能看到Swagger的UI界面，并且能看到配置的API文档信息，说明环境搭建成功。

如果项目中使用了拦截器或者Spring Security等权限管理组件，可能会拦截Swagger的相关资源，需要额外添加放行规则，避免无法访问Swagger界面。以拦截器为例，需要在拦截器的排除路径中添加如下规则：

import org.springframework.context.annotation.Configuration;
import org.springframework.web.servlet.config.annotation.InterceptorRegistry;
import org.springframework.web.servlet.config.annotation.ResourceHandlerRegistry;
import org.springframework.web.servlet.config.annotation.WebMvcConfigurationSupport;

@Configuration
public class WebConfig extends WebMvcConfigurationSupport {

    @Override
    protected void addInterceptors(InterceptorRegistry registry) {
        // 添加拦截器规则，排除Swagger相关路径
        registry.addInterceptor(new MyInterceptor())
                .addPathPatterns("/**")
                .excludePathPatterns("/swagger-ui.html")
                .excludePathPatterns("/swagger-resources/**")
                .excludePathPatterns("/webjars/**")
                .excludePathPatterns("/v2/**");
    }

    @Override
    protected void addResourceHandlers(ResourceHandlerRegistry registry) {
        // 映射Swagger静态资源
        registry.addResourceHandler("swagger-ui.html")
                .addResourceLocations("classpath:/META-INF/resources/");
        registry.addResourceHandler("/webjars/**")
                .addResourceLocations("classpath:/META-INF/resources/webjars/");
    }
}

六、接口文档注解使用

为了让生成的API文档更详细，可以在Controller和接口方法上添加Swagger提供的注解，常用的注解有：

下面是一个使用注解的Controller示例：

import io.swagger.annotations.Api;
import io.swagger.annotations.ApiOperation;
import io.swagger.annotations.ApiParam;
import org.springframework.web.bind.annotation.*;

@Api(tags = "用户管理相关接口")
@RestController
@RequestMapping("/user")
public class UserController {

    @ApiOperation(value = "获取用户详情", notes = "根据用户ID查询用户详细信息")
    @GetMapping("/{id}")
    public String getUserById(@ApiParam(value = "用户ID", required = true) @PathVariable Long id) {
        return "用户ID：" + id;
    }

    @ApiOperation(value = "新增用户", notes = "提交用户信息创建新用户")
    @PostMapping("/add")
    public String addUser(@ApiParam(value = "用户名称", required = true) @RequestParam String name) {
        return "新增用户：" + name;
    }
}

添加注解后，刷新Swagger UI界面，就能看到更详细的接口说明、参数说明，提升文档的可读性。

JavaAPI文档生成SwaggerSpring_Boot环境配置修改时间：2026-07-01 17:57:44