【Swagger】Swagger3.0的使用

相比于Swagger2，Swagger3拥有以下优点

• 更好看的UI
• 修复了一些bug

创建了一个Spring boot项目，接口写完之后，通过Swagger-ui访问调试接口，在浏览器中输入http://localhost:8080/swagger-ui.html 可以正常访问，但是控制台报错java.lang.NumberFormatException: For input string: ""，

 根据报错内容显示，是因为输入了 空字符串""，而空字符串无法转为 Number 类型

使用上的区别

新版本和老版本的区别主要体现在以下 几个方面：

• 依赖项的添加不同：新版本只需要添加一项，而老版本需要添加两项； 

老版本 

    io.springfox
    springfox-swagger2
    2.9.2



    io.springfox
    springfox-swagger-ui
    2.9.2

 新版本

    io.springfox
    springfox-boot-starter
    3.0.0

•  启动 Swagger 的注解不同：新版本使用的是 @EnableOpenApi，而老版本是 @EnableSwagger2
• Swagger UI 访问地址不同：新版本访问地址是“http://localhost:8080/swagger-ui/”，而老版本访问地址是“http://localhost:8080/swagger-ui.html”

config配置如下：

@Configuration
@EnableOpenApi
public class Swagger {

    //是否开启swagger，正式环境一般是需要关闭的，可根据springboot的多环境配置进行设置
    @Value(value = "${swagger.enabled}")
    Boolean swaggerEnabled;

    @Bean
    public Docket docket(){
        return new Docket(DocumentationType.OAS_30)
                .apiInfo(apiInfo())
                .enable(swaggerEnabled)
                .groupName("Corey")
                .select()
                .apis(RequestHandlerSelectors.basePackage("com.example.team.controller"))
                .paths(PathSelectors.any())
                .build();
    }


    @SuppressWarnings("all")
    public ApiInfo apiInfo(){
        return new ApiInfo(
                "team api",
                "team project",
                "v1.0",
                "1234@qq.com", //开发者团队的邮箱
                "Corey",
                "Apache 2.0",  //许可证
                "http://www.apache.org/licenses/LICENSE-2.0" //许可证链接
        );
    }
}

Swagger3添加token 

import io.swagger.v3.oas.models.security.SecurityScheme;
import lombok.extern.slf4j.Slf4j;
import org.springframework.beans.factory.annotation.Value;
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.oas.annotations.EnableOpenApi;
import springfox.documentation.service.ApiInfo;
import springfox.documentation.service.ApiKey;
import springfox.documentation.service.AuthorizationScope;
import springfox.documentation.service.SecurityReference;
import springfox.documentation.spi.DocumentationType;
import springfox.documentation.spi.service.contexts.SecurityContext;
import springfox.documentation.spring.web.plugins.Docket;

import java.util.Arrays;
import java.util.List;

import static java.util.Collections.singletonList;


@Slf4j
@Configuration
@EnableOpenApi
public class SwaggerConfig {

    //是否开启swagger，正式环境一般是需要关闭的，可根据springboot的多环境配置进行设置
    @Value(value = "${swagger.enabled}")
    Boolean swaggerEnabled;

    private List defaultAuth() {
        AuthorizationScope authorizationScope
                = new AuthorizationScope("global", "accessEverything");
        AuthorizationScope[] authorizationScopes = new AuthorizationScope[1];
        authorizationScopes[0] = authorizationScope;
        return singletonList(
                new SecurityReference("token", authorizationScopes));
    }

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

    @Bean
    @SuppressWarnings("all")
    public Docket docket() {
        log.info("swagger.enabled: " + swaggerEnabled);
        return new Docket(DocumentationType.OAS_30)
                .apiInfo(apiInfo())
                .enable(swaggerEnabled)
                .groupName("Corey")
                .select()
                .apis(RequestHandlerSelectors.basePackage("com.corey.team.controller")
                )
                .paths(PathSelectors.any())
                .build()
                .securityContexts(Arrays.asList(securityContext()))
                .securitySchemes(Arrays.asList(new ApiKey("token", "token", SecurityScheme.In.HEADER.name())));
    }

    @SuppressWarnings("all")
    public ApiInfo apiInfo() {
        return new ApiInfo(
                "team api",
                "team api",
                "V0.1",
                "/team",
                "Corey",
                "Apache 2.0",
                "null"
        );
    }
}