SpringBoot 2.6 內建 swagger 3.0

高版本SpringBoot內建swagger 3.0

為了友善線上測試API，相信很多項目都沒有棄用swagger，swagger依然是線上文檔生成優秀架構。如今swagger也疊代到3.0，整體ui風格相比較swagger2更加整潔，配置方面也調整了不少，非常容易踩坑~

1、引入依賴坐标

<!-- https://mvnrepository.com/artifact/io.springfox/springfox-boot-starter -->
 <dependency>
     <groupId>io.springfox</groupId>
     <artifactId>springfox-boot-starter</artifactId>
     <version>3.0.0</version>
 </dependency>
           

2、主程式添加

@EnableOpenApi

注解，這是

swagger 3.0

新增的注解

@EnableOpenApi
@SpringBootApplication
public class WxStubApplication {
    public static void main(String[] args) {
        SpringApplication.run(WxStubApplication.class, args);
    }
}
           

3、修改

SpringMVC

預設路徑比對政策（因為

Springfox

使用的路徑比對是基于

AntPathMatcher

的，而

Spring Boot 2.6.X

使用的是

PathPatternMatcher

）

# swagger3
spring.mvc.pathmatch.matching-strategy=ant_path_matcher
           

4、編寫配置類，配置

swagger

/**
 * @description:
 * @author: laizhenghua
 * @date: 2022/8/30 20:32
 */
@Configuration
public class SwaggerConfiguration {
    @Bean
    public Docket docket() {
        return new Docket(DocumentationType.OAS_30)
                .select().apis(RequestHandlerSelectors.basePackage("com.laizhenghua.wxstub.controller"))
                .paths(PathSelectors.any()).build()
                .apiInfo(setApiInfo());
    }
    private ApiInfo setApiInfo() {
        Contact contact = new Contact("laizhenghua", "https://blog.csdn.net/m0_46357847", "[email protected]");
        ApiInfo info = new ApiInfo("微信消息推送助手", "每天定時推送微信消息", "v1.0",
                "https://blog.csdn.net/m0_46357847", contact, "Apache 2.0", "", new ArrayList<VendorExtension>());
        return info;
    }

    @Bean
    public static BeanPostProcessor springfoxHandlerProviderBeanPostProcessor() {
        return new BeanPostProcessor() {

            @Override
            public Object postProcessAfterInitialization(Object bean, String beanName) throws BeansException {
                if (bean instanceof WebMvcRequestHandlerProvider || bean instanceof WebFluxRequestHandlerProvider) {
                    customizeSpringfoxHandlerMappings(getHandlerMappings(bean));
                }
                return bean;
            }

            private <T extends RequestMappingInfoHandlerMapping> void customizeSpringfoxHandlerMappings(List<T> mappings) {
                List<T> copy = mappings.stream()
                        .filter(mapping -> mapping.getPatternParser() == null)
                        .collect(Collectors.toList());
                mappings.clear();
                mappings.addAll(copy);
            }

            @SuppressWarnings("unchecked")
            private List<RequestMappingInfoHandlerMapping> getHandlerMappings(Object bean) {
                try {
                    Field field = ReflectionUtils.findField(bean.getClass(), "handlerMappings");
                    field.setAccessible(true);
                    return (List<RequestMappingInfoHandlerMapping>) field.get(bean);
                } catch (IllegalArgumentException | IllegalAccessException e) {
                    throw new IllegalStateException(e);
                }
            }
        };
    }
}
           

5、使用

swagger 3.0

方式也是和

2.0

一樣，隻需在類、方法、參數上添加相應的注解即可

/**
 * @description: PushController
 * @author: laizhenghua
 * @date: 2022/8/30 12:39
 */
@Api(tags = "APP-微信消息推送助手")
@RestController
@RequestMapping(RestURL.PUSH_URL)
public class PushController {

    @Autowired
    private PushService pushService;

    @ApiOperation(value = "推送：每天定時推送微信消息", notes = "api/push/message", response = R.class)
    @RequestMapping(value = "/message", method = RequestMethod.GET)
    public R pushMessage(@ApiParam(value = "微信号", required = true) String wxId) {
        return R.ok().put("data", pushService.pushMessage());
    }
}
           

6、效果圖（通路

http://127.0.0.1:8080/swagger-ui/index.html

）