是时候把你的Sawgger2.x升级到Swagger-ui 3.0.0了

介绍

Swagger 是可以为我们提供通过代码和注解自动生成Rest API 文档，这一点对于保证 API 文档的及时性将有很大的帮助

Swagger 是一套基于 OpenAPI 规范（OpenAPI Specification，OAS）构建的开源工具，可以帮助我们设计、构建、记录以及使用 Rest API。

Swagger 提供了一个可视化的UI页面展示描述文件。接口的调用方、测试、项目经理等都可以在该页面中对相关接口进行查阅和做一些简单的接口请求。该项目支持在线导入描述文件和本地部署UI项目。

新特性

• 移除了2.x版本的冲突版本，移除了guava等。
• 移除了@EnableSwagger2。
• 新增了springfox-boot-starter。
• 其他。

集成

删除之前的依赖，直接使用最新的starter方式。

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

然后应用主类增加注解@EnableOpenApi，删除之前版本的SwaggerConfig.java

启动项目，访问地址：http://localhost:8088/swagger-ui/index.html，注意2.x版本中访问的地址的为http://localhost:8088/swagger-ui.html

配置

• 拦截配置

@Configuration
public class WebMvcConfig implements WebMvcConfigurer {
     
    @Override
    public void addResourceHandlers(ResourceHandlerRegistry registry) {
     
        registry.
                addResourceHandler("/swagger-ui/**")
                .addResourceLocations("classpath:/META-INF/resources/webjars/springfox-	swagger-ui/")
                .resourceChain(false);
    }

    @Override
    public void addViewControllers(ViewControllerRegistry registry) {
     
        registry.addViewController("/swagger-ui/")
                .setViewName("forward:/swagger-ui/index.html");
    }
}

• Swagger描述配置

@Configuration
public class Swagger3Config {
     
    @Bean
    public Docket createRestApi() {
     
        return new Docket(DocumentationType.OAS_30)
                .apiInfo(apiInfo())
                .select()
                .apis(RequestHandlerSelectors.withMethodAnnotation(ApiOperation.class))
                .paths(PathSelectors.any())
                .build();
    }

    private ApiInfo apiInfo() {
     
        return new ApiInfoBuilder()
                .title("Swagger3接口文档")
                .description("文档描述")
                .contact(new Contact("wuhao", "#", "[email protected]"))
                .version("1.0")
                .build();
    }
}

• SpringSecurity拦截配置

 private static final String[] AUTH_WHITELIST = {
     
            "/swagger-ui.html",
            "/swagger-ui/*",
            "/swagger-resources/**",
            "/v2/api-docs",
            "/v3/api-docs",
            "/webjars/**"
    };
 .antMatchers(AUTH_WHITELIST).permitAll()

常用注解

• @Api：用在controller类，描述API接口
• @ApiOperation：描述接口方法
• @ApiModel：描述对象
• @ApiModelProperty：描述对象属性
• @ApiImplicitParams：描述接口参数
• @ApiResponses：描述接口响应
• @ApiIgnore：忽略接口方法