相比于Swagger2,Swagger3拥有以下优点
- 更好看的UI
- 修复了一些bug
创建了一个Spring boot项目,接口写完之后,通过Swagger-ui访问调试接口,在浏览器中输入http://localhost:8080/swagger-ui.html 可以正常访问,但是控制台报错java.lang.NumberFormatException: For input string: "",
根据报错内容显示,是因为输入了 空字符串"",而空字符串无法转为 Number 类型
使用上的区别新版本和老版本的区别主要体现在以下 几个方面:
- 依赖项的添加不同:新版本只需要添加一项,而老版本需要添加两项;
老版本
io.springfox springfox-swagger22.9.2 io.springfox springfox-swagger-ui2.9.2
新版本
io.springfox springfox-boot-starter3.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 ListdefaultAuth() { 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" ); } }