SpringBoot整合Swagger (Springfox 3.0.0)

原创已于 2025-03-23 14:48:38 修改 · 485 阅读

3 ·

CC 4.0 BY-SA版权

文章标签：

#spring boot #java #后端

于 2025-03-15 14:54:02 首次发布

Swagger 专栏收录该内容

2 篇文章

订阅专栏

Maven依赖

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

配置文件设置

# 解决"Unable to infer base url"错误的关键配置
spring:
  mvc:
    pathmatch:
      matching-strategy: ant_path_matcher

# Swagger配置
springfox:
  documentation:
    swagger-ui:
      enabled: true              # 启用Swagger UI界面
    swagger:
      v2:
        enabled: true            # 启用Swagger 2.0 API文档
    open-api:
      enabled: true              # 启用OpenAPI 3.0文档
    auto-startup: true           # 自动启动Swagger
    
# 如果您使用的是Swagger UI分组功能
    swagger-groups:
      - group-name: 默认分组
        paths-to-match: /**
        packages-to-scan: com.example.controller

# 日志配置，帮助调试Swagger问题
logging:
  level:
    springfox: INFO
    
# 服务器配置，如果有上下文路径
# server:
#   servlet:
#     context-path: /api

Swagger配置类

package com.example.config;

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;

@Configuration
public class SwaggerConfig {

    @Bean
    public Docket api() {
        return new Docket(DocumentationType.OAS_30)
                // 明确设置主机信息，解决"Unable to infer base url"错误
                .host("localhost:8080")  // 根据实际部署环境更改
                .apiInfo(apiInfo())
                .select()
                .apis(RequestHandlerSelectors.basePackage("com.example.controller"))  // 设置要暴露的API的包路径
                .paths(PathSelectors.any())
                .build();
    }

    private ApiInfo apiInfo() {
        return new ApiInfoBuilder()
                .title("API文档")
                .description("SpringBoot整合Swagger3示例")
                .version("v1.0.0")
                .contact(new Contact("开发团队", "https://example.com", "dev@example.com"))
                .build();
    }
}

WebMvc配置类

package com.example.config;

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

@Configuration
public class WebMvcConfig implements WebMvcConfigurer {

    @Override
    public void addResourceHandlers(ResourceHandlerRegistry registry) {
        // 添加Swagger UI资源处理器，辅助解决"Unable to infer base url"错误
        registry.addResourceHandler("/swagger-ui/**")
                .addResourceLocations("classpath:/META-INF/resources/webjars/springfox-swagger-ui/");
        registry.addResourceHandler("/webjars/**")
                .addResourceLocations("classpath:/META-INF/resources/webjars/");
    }
}

访问Swagger UI

检查安全配置，如果使用Spring Security，确保放行Swagger相关路径

@Configuration
@EnableWebSecurity
public class SecurityConfig extends WebSecurityConfigurerAdapter {

    @Override
    protected void configure(HttpSecurity http) throws Exception {
        http.authorizeRequests()
            // 放行Swagger相关路径
            .antMatchers("/swagger-ui/**", "/swagger-resources/**", "/v3/api-docs/**", "/v2/api-docs/**", "/webjars/**")
            .permitAll()
            .anyRequest().authenticated();
            // 其他安全配置
    }
}