Swagger与Spring Boot在Linux下的集成指南

1. 集成概述

Swagger是一个强大的API文档工具，与Spring Boot集成可以自动生成RESTful API文档。在Linux环境下，集成过程与其他操作系统类似，主要区别在于部署和运行环境。

2. 集成步骤

2.1 添加依赖

在pom.xml中添加Swagger相关依赖：

<!-- SpringFox Swagger2 -->
<dependency>
    <groupId>io.springfox</groupId>
    <artifactId>springfox-swagger2</artifactId>
    <version>2.9.2</version>
</dependency>

<!-- SpringFox Swagger UI -->
<dependency>
    <groupId>io.springfox</groupId>
    <artifactId>springfox-swagger-ui</artifactId>
    <version>2.9.2</version>
</dependency>

<!-- 如果使用Spring Boot 3.x，需要使用SpringDoc替代 -->
<dependency>
    <groupId>org.springdoc</groupId>
    <artifactId>springdoc-openapi-ui</artifactId>
    <version>1.6.14</version>
</dependency>

2.2 配置Swagger

创建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.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.your.package"))
                .paths(PathSelectors.any())
                .build()
                .apiInfo(apiInfo());
    }

    private ApiInfo apiInfo() {
        return new ApiInfoBuilder()
                .title("API文档")
                .description("Spring Boot集成Swagger")
                .version("1.0")
                .build();
    }
}

2.3 添加API注解

在Controller类和方法上添加Swagger注解：

import io.swagger.annotations.Api;
import io.swagger.annotations.ApiOperation;

@RestController
@RequestMapping("/api")
@Api(tags = "用户管理API")
public class UserController {

    @GetMapping("/users")
    @ApiOperation("获取所有用户")
    public List<User> getAllUsers() {
        // 实现代码
    }
}

3. Linux环境下的特殊考虑

3.1 启动应用

在Linux下启动Spring Boot应用：

# 使用Maven打包
mvn clean package

# 运行应用
java -jar target/your-application.jar

3.2 访问Swagger UI

应用启动后，可以通过以下URL访问Swagger UI：

http://your-server-ip:8080/swagger-ui.html

如果使用SpringDoc (Spring Boot 3.x):

http://your-server-ip:8080/swagger-ui/index.html

3.3 防火墙配置

确保Linux防火墙允许访问Swagger UI端口：

# 查看防火墙状态
sudo ufw status

# 允许8080端口
sudo ufw allow 8080/tcp

4. 常见问题解决

4.1 访问404错误

• 检查应用是否正常启动
• 确认访问路径是否正确
• 检查Spring Security配置是否拦截了Swagger路径

4.2 跨域问题

如果前端与API不在同一域名下，需要配置CORS：

@Configuration
public class WebConfig implements WebMvcConfigurer {
    @Override
    public void addCorsMappings(CorsRegistry registry) {
        registry.addMapping("/**")
                .allowedOrigins("*")
                .allowedMethods("*")
                .allowedHeaders("*");
    }
}

4.3 生产环境禁用Swagger

建议在生产环境禁用Swagger UI：

@Profile("!prod")
@Configuration
@EnableSwagger2
public class SwaggerConfig {
    // 配置内容
}

5. 高级配置

5.1 使用SpringDoc (Spring Boot 3.x)

Spring Boot 3.x不再支持SpringFox，需要使用SpringDoc:

@Configuration
public class OpenApiConfig {
    @Bean
    public OpenAPI customOpenAPI() {
        return new OpenAPI()
                .info(new Info()
                        .title("API文档")
                        .version("1.0")
                        .description("Spring Boot 3集成Swagger"));
    }
}

5.2 分组API

@Bean
public Docket userApi() {
    return new Docket(DocumentationType.SWAGGER_2)
            .groupName("用户API")
            .select()
            .apis(RequestHandlerSelectors.basePackage("com.your.user.package"))
            .paths(PathSelectors.any())
            .build();
}

通过以上步骤，您可以在Linux环境下成功集成Swagger与Spring Boot，并生成美观的API文档。