怎么集成Swagger生成接口文档？

本文目录导读：

1. Spring Boot集成Swagger
2. Spring Boot 3.x + Springdoc (推荐新项目使用)
3. 代码中使用注解
4. 高级配置
5. 访问文档
6. 生产环境配置
7. 安全配置
8. 注意事项

我来详细说明如何集成Swagger生成接口文档，主要分为Spring Boot和Spring Cloud两种常见场景。

Spring Boot集成Swagger

1 添加依赖 (Spring Boot 2.x + Springfox)

<!-- Maven依赖 -->
<dependency>
    <groupId>io.springfox</groupId>
    <artifactId>springfox-swagger2</artifactId>
    <version>2.9.2</version>
</dependency>
<dependency>
    <groupId>io.springfox</groupId>
    <artifactId>springfox-swagger-ui</artifactId>
    <version>2.9.2</version>
</dependency>

2 配置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("API文档描述")
                .version("1.0")
                .contact(new Contact("作者名", "网址", "邮箱"))
                .build();
    }
}

Spring Boot 3.x + Springdoc (推荐新项目使用)

1 添加依赖

<dependency>
    <groupId>org.springdoc</groupId>
    <artifactId>springdoc-openapi-starter-webmvc-ui</artifactId>
    <version>2.3.0</version>
</dependency>

2 基本配置即可使用

# application.yml配置
springdoc:
  api-docs:
    path: /api-docs
  swagger-ui:
    path: /swagger-ui.html

代码中使用注解

1 Controller层注解

@RestController
@RequestMapping("/api/users")
@Api(tags = "用户管理")
public class UserController {
    @GetMapping("/{id}")
    @ApiOperation("根据ID获取用户信息")
    @ApiImplicitParams({
        @ApiImplicitParam(name = "id", value = "用户ID", required = true, dataType = "Long", paramType = "path")
    })
    public Result<User> getUser(@PathVariable Long id) {
        // 实现代码
    }
    @PostMapping
    @ApiOperation("创建用户")
    public Result<User> createUser(@RequestBody @Valid UserCreateDTO dto) {
        // 实现代码
    }
}

2 实体类注解

@ApiModel(value = "用户创建请求")
public class UserCreateDTO {
    @ApiModelProperty(value = "用户名", required = true, example = "zhangsan")
    @NotBlank(message = "用户名不能为空")
    private String username;
    @ApiModelProperty(value = "邮箱", example = "zhangsan@example.com")
    @Email(message = "邮箱格式不正确")
    private String email;
    @ApiModelProperty(value = "年龄", example = "25")
    @Min(value = 1, message = "年龄最小为1")
    @Max(value = 150, message = "年龄最大为150")
    private Integer age;
}

高级配置

1 自定义分组

@Bean
public Docket api1() {
    return new Docket(DocumentationType.SWAGGER_2)
            .groupName("用户接口")
            .select()
            .apis(RequestHandlerSelectors.basePackage("com.example.controller.user"))
            .build();
}
@Bean
public Docket api2() {
    return new Docket(DocumentationType.SWAGGER_2)
            .groupName("订单接口")
            .select()
            .apis(RequestHandlerSelectors.basePackage("com.example.controller.order"))
            .build();
}

2 全局参数配置

@Bean
public Docket api() {
    // 全局请求参数
    List<Parameter> globalParams = new ArrayList<>();
    globalParams.add(new ParameterBuilder()
            .name("Authorization")
            .description("Token")
            .modelRef(new ModelRef("string"))
            .parameterType("header")
            .required(false)
            .build());
    return new Docket(DocumentationType.SWAGGER_2)
            .globalOperationParameters(globalParams)
            .select()
            .apis(RequestHandlerSelectors.any())
            .paths(PathSelectors.any())
            .build();
}

访问文档

启动项目后访问：

• Swagger UI: http://localhost:8080/swagger-ui.html (Springfox)
• Swagger UI: http://localhost:8080/swagger-ui/index.html (Springdoc)
• JSON格式: http://localhost:8080/v2/api-docs (Springfox)
• JSON格式: http://localhost:8080/api-docs (Springdoc)

生产环境配置

@Configuration
@EnableSwagger2
@Profile({"dev", "test"}) // 只在开发测试环境开启
public class SwaggerConfig {
    // 配置内容同上
}

安全配置

@Bean
public Docket api() {
    return new Docket(DocumentationType.SWAGGER_2)
            .securitySchemes(Arrays.asList(apiKey()))
            .select()
            .apis(RequestHandlerSelectors.any())
            .build();
}
private ApiKey apiKey() {
    return new ApiKey("JWT", "Authorization", "header");
}

注意事项

1. 版本兼容性: 注意Spring Boot版本与Swagger版本的兼容性
2. 性能影响: 生产环境建议关闭Swagger
3. 安全考虑: 避免在公开接口中暴露敏感信息
4. 注解规范: 规范的注解可以提高文档可读性

选择建议：

• Spring Boot < 3.0: 使用Springfox
• Spring Boot >= 3.0: 使用Springdoc
• 新项目: 推荐直接使用Springdoc

这样配置完成后,访问对应URL即可看到自动生成的API文档。