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

1. 概述

Swagger是一个强大的API文档工具，可以帮助开发者设计、构建、记录和使用RESTful Web服务。在Linux环境下将Swagger与Spring Boot结合使用，可以方便地生成和测试API文档。

2. 集成步骤

2.1 添加依赖

在Spring Boot项目的pom.xml中添加Swagger相关依赖：

<!-- Swagger 2 -->
<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>

或者使用Swagger 3（推荐）：

<!-- Swagger 3 -->
<dependency>
    <groupId>io.springfox</groupId>
    <artifactId>springfox-boot-starter</artifactId>
    <version>3.0.0</version>
</dependency>

2.2 配置Swagger

创建一个配置类SwaggerConfig.java：

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.any())
                .paths(PathSelectors.any())
                .build();
    }
}

对于Swagger 3：

import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import io.swagger.v3.oas.models.OpenAPI;
import io.swagger.v3.oas.models.info.Info;

@Configuration
public class SwaggerConfig {
    @Bean
    public OpenAPI springShopOpenAPI() {
        return new OpenAPI()
                .info(new Info().title("Spring Boot API")
                .description("Spring Boot application")
                .version("v1.0.0"));
    }
}

2.3 添加API文档注解

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

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

@RestController
@RequestMapping("/api")
@Api(value = "用户管理", tags = "用户管理接口")
public class UserController {

    @GetMapping("/users/{id}")
    @ApiOperation(value = "获取用户信息", notes = "根据用户ID获取用户详细信息")
    public User getUser(@PathVariable Long id) {
        // 实现代码
    }

    @PostMapping("/users")
    @ApiOperation(value = "创建用户", notes = "创建新用户")
    public User createUser(@RequestBody User user) {
        // 实现代码
    }
}

3. Linux环境下的特殊考虑

3.1 生产环境配置

在生产环境中，你可能希望禁用Swagger UI：

# application.properties
springfox.documentation.swagger-ui.enabled=false

或者根据环境变量动态配置：

@Configuration
@EnableSwagger2
public class SwaggerConfig {

    @Value("${swagger.enabled:false}")
    private boolean swaggerEnabled;

    @Bean
    public Docket api() {
        return new Docket(DocumentationType.SWAGGER_2)
                .enable(swaggerEnabled)
                .select()
                .apis(RequestHandlerSelectors.any())
                .paths(PathSelectors.any())
                .build();
    }
}

3.2 安全配置

在Linux生产环境中，确保Swagger端点受到保护：

import org.springframework.security.config.annotation.web.builders.HttpSecurity;
import org.springframework.security.config.annotation.web.configuration.WebSecurityConfigurerAdapter;

@Configuration
public class SecurityConfig extends WebSecurityConfigurerAdapter {
    @Override
    protected void configure(HttpSecurity http) throws Exception {
        http.authorizeRequests()
            .antMatchers("/swagger-ui/**", "/v3/api-docs/**").hasRole("ADMIN")
            // 其他安全配置
            .and()
            .httpBasic();
    }
}

4. 访问Swagger UI

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

• Swagger 2: http://<your-server-ip>:<port>/swagger-ui.html
• Swagger 3: http://<your-server-ip>:<port>/swagger-ui/

5. 常见问题解决

5.1 404错误

如果访问Swagger UI时出现404错误：

1. 检查依赖是否正确添加
2. 确保没有自定义的Servlet路径配置
3. 检查是否有安全拦截

5.2 跨域问题

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

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

5.3 性能优化

对于大型API，可以限制扫描的包路径：

@Bean
public Docket api() {
    return new Docket(DocumentationType.SWAGGER_2)
            .select()
            .apis(RequestHandlerSelectors.basePackage("com.your.package"))
            .paths(PathSelectors.any())
            .build();
}

6. 高级配置

6.1 添加认证支持

@Bean
public Docket api() {
    return new Docket(DocumentationType.SWAGGER_2)
            .securitySchemes(Arrays.asList(apiKey()))
            .securityContexts(Arrays.asList(securityContext()))
            // 其他配置
            .build();
}

private ApiKey apiKey() {
    return new ApiKey("JWT", "Authorization", "header");
}

private SecurityContext securityContext() {
    return SecurityContext.builder()
            .securityReferences(defaultAuth())
            .forPaths(PathSelectors.any())
            .build();
}

List<SecurityReference> defaultAuth() {
    AuthorizationScope authorizationScope = new AuthorizationScope("global", "accessEverything");
    AuthorizationScope[] authorizationScopes = new AuthorizationScope[1];
    authorizationScopes[0] = authorizationScope;
    return Arrays.asList(new SecurityReference("JWT", authorizationScopes));
}

6.2 自定义UI

可以下载Swagger UI资源并自定义：

1. 从https://github.com/swagger-api/swagger-ui下载
2. 将dist目录内容复制到src/main/resources/static/swagger-ui
3. 修改index.html中的URL指向你的API文档JSON

7. 结论

在Linux环境下集成Swagger与Spring Boot可以大大提升API开发效率，方便团队协作和前后端对接。通过合理配置，可以在开发环境中充分利用Swagger的强大功能，同时确保生产环境的安全性。