swagger3.0使用及https问题处理

swagger 文档在日常开发中，用得比较多，往往我们都是手动配置，swagger3.0之后，直接就上了一个swagger-starter,用起来更方便了。swagger3.0发生了很多变化，比如包名、注解、访问路径等都有所变化。具体自己去体会了，我就是不多说了，直接开干。

swagger3.0项目地址: https://github.com/springfox/springfox

第一步： 基础准备

1.一个springboot项目
2.swagger3.0依赖

    io.springfox
    springfox-boot-starter
    3.0.0

第二步: 整合

1.在springboot项目pom中添加入swagger3.0依赖
2.在启动类上加新版注解@EnableOpenApi

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

}

3.添加一个接口测试controller：

import io.swagger.annotations.Api;
import io.swagger.annotations.ApiOperation;
import org.springframework.web.bind.annotation.GetMapping;
import org.springframework.web.bind.annotation.RestController;

@Api(tags = "swagger3.0接口")
@RestController
public class ApiController {
   @ApiOperation("获取列表")
   @GetMapping("/list")
   public String list(){
       return "swagger3.0";
   }
}

4.直接启动搞定：注意 访问路径 http://localhost:8080/swagger-ui/index.html，和2不一样了。

image.png

轻轻松松零配置就把swagger整合跑起来了，比之前2.x的版本方便了很多了吧。
5.虽说config可以不配置，但是starter的配置中并没有把其他一些配置的信息整合进去，所以，我们需要修改文档中某些信息时，还是得手动配置一下config，熟悉的配方、熟悉的味道。

import io.swagger.annotations.ApiOperation;
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 Swagger3Config {

    @Bean
    public Docket createApi(){
        
        return new Docket(DocumentationType.OAS_30)
                .apiInfo(apiInfo())
                .select()
                .apis(RequestHandlerSelectors.withMethodAnnotation(ApiOperation.class))
                .paths(PathSelectors.any())
                .build();
    }
    
    public ApiInfo apiInfo(){
        
        return new ApiInfoBuilder()
                .title("swagger3.0文档")
                .description("文件描述")
                .contact(new Contact("zzj","#","[email protected]"))
                .version("1.0")
                .build();
    }

}

再一运行：

image.png

ok了，就搞定了。

第三步: bug修复

当使用https后界面上的services地址不会随着你的项目域名变https时自动变https,如下图:

image.png

当然,这个bug官方会在3.0.1版本中修复,https://github.com/springfox/springfox/issues/3468，目前也是可以解决这个问题的，自定义swagger拦截器，借鉴了https://github.com/springfox/springfox/issues/3531,

import io.swagger.v3.oas.models.OpenAPI;
import io.swagger.v3.oas.models.servers.Server;
import org.springframework.stereotype.Component;
import org.springframework.util.StringUtils;
import springfox.documentation.oas.web.OpenApiTransformationContext;
import springfox.documentation.oas.web.WebMvcOpenApiTransformationFilter;
import springfox.documentation.spi.DocumentationType;

import javax.servlet.http.HttpServletRequest;
import java.util.ArrayList;
import java.util.List;

@Component
public class SpringFoxSwaggerHostResolver implements WebMvcOpenApiTransformationFilter {
    @Override
    public OpenAPI transform(OpenApiTransformationContext context) {

        HttpServletRequest request = context.request().get();

        OpenAPI swagger = context.getSpecification();

        String scheme = "http";
        String referer = request.getHeader("Referer");

        if(StringUtils.hasLength(referer)){
            //获取协议
            scheme = referer.split(":")[0];
        }

        List servers = new ArrayList<>();
        String finalScheme = scheme;
        //重新组装server信息
        swagger.getServers().forEach(item->{

            //替换协议,去掉默认端口
            item.setUrl(clearDefaultPort(item.getUrl().replace("http", finalScheme)));
            servers.add(item);
        });
        swagger.setServers(servers);
        return swagger;
    }

    //清除默认端口
    private String clearDefaultPort(String url){

        String port = url.split(":")[2];
        if("80".equals(port)||"443".equals(port)){
          return url.replace(":80","").replace(":443","");
        }
        return url;
    }

    @Override
    public boolean supports(DocumentationType documentationType) {
        return documentationType.equals(DocumentationType.OAS_30);
    }
}

此时再重新启动项目:

image.png

就可以正常了，当然这只是我自己处理的一个思路，具体实现可以各抒己见。

第四步：总结

我也是初次使用swagger3，因为之前一直用2的版本，因为搭建的springcloud项目中使用gateway网关，而swagger3，支持webflux，所以试用了一下3的版本，集成倒是感觉还是很方便的，直到发布到测试环境搞了https之后，才发现以上的bug，网上搜索swagger3.0相关问题半天，没有结果，最后跑到github，找到swagger3项目地址看了issues,才发现原来也有人提出了相同的问题，后面在issues中找到了解决办法，所以呢分享了这么一个经历，便于同学们参考。总的来说还是解决了问题，等3.0 .1之后，看看官方修复的结果，再做调整吧。喜欢我的文章记得关注我，只分享干活，偶尔扯扯淡，其余就是干。

最后的最后：demo地址:https://gitee.com/zzj1992/swagger3-demo.git