Java整合Swagger生成API文档教程

Java项目集成Swagger可自动生成清晰、交互式的API文档，大幅提升开发协作效率与接口维护质量；本文详解了Spring Boot 2.x下使用Springfox（需配置@EnableSwagger2和Docket）与Spring Boot 3+推荐的SpringDoc（零配置、开箱即用）两大主流方案，涵盖依赖引入、访问路径（如/swagger-ui/index.html）、接口注解（@Tag/@Operation/@Parameter等）增强文档可读性，以及生产环境安全关闭、JWT认证集成和中文支持等关键实践，助你快速落地专业级API文档体系。

Java项目中集成Swagger可以快速实现API文档的自动生成，提升开发效率，减少手动编写文档的工作量。目前主流使用的是Spring Boot项目结合Swagger（通常使用Springfox或SpringDoc）来自动生成接口文档。

1. 使用Springfox集成Swagger

Springfox是较早流行的Swagger集成工具，适用于Spring Boot 2.x版本。

• 添加Maven依赖：在pom.xml中引入Springfox Swagger依赖：

    io.springfox
    springfox-swagger2
    2.9.2


    io.springfox
    springfox-swagger-ui
    2.9.2

  

• 配置Swagger：创建一个配置类启用Swagger：

@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()
            .apiInfo(apiInfo());
    }

    private ApiInfo apiInfo() {
        return new ApiInfoBuilder()
            .title("项目API文档")
            .description("基于Swagger生成的RESTful API文档")
            .version("1.0")
            .build();
    }
}
  

• 启动项目后访问：
  浏览器打开 http://localhost:8080/swagger-ui.html 即可查看自动生成的API文档。

2. 使用SpringDoc替代Springfox（推荐用于Spring Boot 3+）

Spring Boot 3以后不再兼容Springfox，推荐使用SpringDoc OpenAPI，它支持OpenAPI 3规范，且无需额外配置即可自动集成。

• 添加SpringDoc依赖：

    org.springdoc
    springdoc-openapi-starter-webmvc-ui
    2.0.2

  

• 无需额外配置类，SpringDoc会自动扫描所有Controller并生成文档。
• 访问地址：
  启动项目后访问 http://localhost:8080/swagger-ui.html 或 http://localhost:8080/swagger-ui/index.html 查看UI界面。

3. 添加接口注解丰富文档内容

通过在Controller和方法上添加Swagger注解，可以让文档更清晰。

• @Tag(name = "用户模块")：给Controller分类
• @Operation(summary = "获取用户信息", description = "根据ID查询用户")：描述接口功能
• @Parameter(description = "用户ID", required = true)：描述参数
• @ApiResponse：定义响应状态码和说明

示例：

@RestController
@Tag(name = "用户管理")
public class UserController {

    @GetMapping("/user/{id}")
    @Operation(summary = "获取用户详情")
    public ResponseEntity getUserById(
        @Parameter(description = "用户ID", required = true) 
        @PathVariable Long id) {
        // 业务逻辑
        return ResponseEntity.ok(new User(id, "张三"));
    }
}
  

4. 注意事项与优化建议

• 生产环境建议关闭Swagger，可通过配置控制：

  springdoc:
    api-docs:
      enabled: false
    swagger-ui:
      enabled: false
      

  并在开发 profile 中开启。
• 支持JWT等安全认证的展示，在配置中加入SecurityScheme即可。
• 支持中文文档，确保项目编码为UTF-8，注解内容可直接写中文。

基本上就这些。选择Springfox还是SpringDoc取决于你的Spring Boot版本。新项目建议直接使用SpringDoc，更轻量、兼容性更好，集成也更简单。

文中关于的知识介绍，希望对你的学习有所帮助！若是受益匪浅，那就动动鼠标收藏这篇《Java整合Swagger生成API文档教程》文章吧，也可关注golang学习网公众号了解相关技术文章。