swagger集成步骤（包含springboot集成与springcloud集成方案

简述swagger:服务端常用的文档页面，可自动通过扫描生成接口文档，也可以通过添加指定的注解显示接口。

我这里主要是在集成springcloud微服务的时候，考虑多个模块的sw能不能集成到一个端口对外开放，因为我们知道微服务的优势就是多个服务分开运行，这样带来的问题就是多个端口开放，与此同时如果配合使用swagger并访问的话，那需要对每个服务的端口单独访问才能看到对应的swagger生成的接口文档，例如：

现在有服务A,端口为5001;服务B,端口为5001；zuul服务，端口5003。

如果你想要看A服务的sw(swagger简称，后续都是),那么就是访问 http://youip:5001:swagger-ui.html,访问B服务的sw就是http://youip:5002:swagger-ui.html.

1.这样是比较不便

2.在采用微服务的时候，我们并不会将这些端口一一对外开放，而是采用zuul(zuul相关这里不讲解可以自行查看一下)等方式，转发服务对外统一只开放一个端口。

所以更好的操作应该是在每个服务中集成sw,在zuul中统一集成各个服务的sw，这样就可以通过一个端口访问多个服务的sw。访问http://youip:5003:swagger-ui.html.就可以在其中看到A，B服务的sw文档内容。

接下来是步骤：

1.在各个服务中集成sw

 1.1添加依赖

<!-- swagger -->
<dependency>
    <groupId>io.springfox</groupId>
    <artifactId>springfox-swagger2</artifactId>
    <version>2.9.2</version>
</dependency>
<!-- swagger-ui -->
<dependency>
    <groupId>io.springfox</groupId>
    <artifactId>springfox-swagger-ui</artifactId>
    <version>2.9.2</version>
</dependency>

在这里添加完依赖后，重新启动服务，sw就算集成完毕(它会自动扫描与生成文档)，可以直接访问 http://ip:服务port/swagger-ui.html 去查看自动生成好的sw.到此我们的第一步，服务中集成sw就完成了。

示例图：

 1.2 拓展：sw 除了方便可自动生成外，当然也可以自定义一些规则，可以通过自己写一个SwaggerConfig的配置，也可以不写，写的话可以自己定制一些规则，这里简单提一下，比如我这里是写了的因为要添加默认的请求头：

@Configuration
@EnableSwagger2
public class SwaggerConfig {

    @Bean
    public Docket createRestApi() {

        //添加head参数start
        ParameterBuilder tokenPar = new ParameterBuilder();
        ParameterBuilder tokenPar2 = new ParameterBuilder();
        List<Parameter> pars = new ArrayList<Parameter>();
        tokenPar.name("token").description("请求token").modelRef(new ModelRef("string")).parameterType("header").required(true).build();
        tokenPar2.name("userId").description("请求userId").modelRef(new ModelRef("string")).parameterType("header").required(true).build();
        pars.add(tokenPar.build());
        pars.add(tokenPar2.build());
        return new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(apiInfo())
                .select()
                .apis(RequestHandlerSelectors.basePackage("com.zq.controller"))//指定包下的才会被扫描
//                .apis(RequestHandlerSelectors.withClassAnnotation(Api.class))//带有指定注解的类才会被扫描
//                .apis(RequestHandlerSelectors.withMethodAnnotation(ApiOperation.class))
                .paths(PathSelectors.any())
                .build()
                .globalOperationParameters(pars);
    }


    private ApiInfo apiInfo() {
        return new ApiInfoBuilder()
                .title("Spring Boot Swagger2 RESTful APIs")
                .description("calligraphy")
                .version("1.0")
                .build();
    }
}

需要在其上面添加@EnableSwagger2注解 这一步，就可完成，至于@Configuration 是用来告诉spring项目这是配置类。

2.第一步只是可以各个服务访问接口，第二步则是要在zuul集成各个服务的sw，可以通过访问一个端口的sw而去访问到多个sw。

 2.1首先还是在zuul中添加sw依赖与1.1完全相同

 2.2 然后不同的是zuul中需要你集成其他的sw，通过写zuul自动省的sw配置，而去访问其他服务的sw（本质上是访问其他服务sw提供的api），而集成一个新的sw.操作如下：

 在application上添加@EnableSwagger2注解  然后写配置文件swaggerconfig.class

/**
 * desc
 * author zhouqi
 * data 2020/10/15
 */
@Configuration
@EnableSwagger2
public class SwaggerConfig {
    @Bean
    public Docket createRestApi() {
        //添加head参数start 这在里可以不要这个
        ParameterBuilder tokenPar = new ParameterBuilder();
        ParameterBuilder tokenPar2 = new ParameterBuilder();
        List<Parameter> pars = new ArrayList<Parameter>();
        pars.add(tokenPar.build());
        pars.add(tokenPar2.build());
        return new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(apiInfo())
                .select()
                .paths(PathSelectors.any())
                .build()
                .globalOperationParameters(pars);
    }

    private ApiInfo apiInfo() {
        return new ApiInfoBuilder()
                .version("1.0")
                .build();
    }

    /**
     * 重点是这一步，集成其他的sw
     */
    @Configuration
    @Primary
    public class MySwaggerResourceProvider implements SwaggerResourcesProvider {

        @Autowired
        ZuulProperties zuulProperties;

        @Override
        public List<SwaggerResource> get() {
            List resources = new ArrayList<>();
            //去访问其他的服务的路由地址对应sw的api，这样在zuul中集成各个服务的sw文档
            zuulProperties.getRoutes().values().stream().forEach(zuulRoute -> {
                //为了认清地址api
                        resources.add(swaggerResource(zuulRoute.getServiceId(), zuulRoute.getPath().replace("**", "v2/api-docs"), "1.0"));
                    }
            );
            return resources;
        }

        private SwaggerResource swaggerResource(String name, String location, String version) {
            SwaggerResource swaggerResource = new SwaggerResource();
            swaggerResource.setName(name);
            swaggerResource.setLocation(location);
            swaggerResource.setSwaggerVersion(version);
            return swaggerResource;
        }
    }
}

这样zuul中的sw也算是配置好了，然后逐一的启动服务与zuul，访问zuul中你就可以看到各个服务的sw文档了。

示例图：（我这里是多个服务，可自行选择，它会显示出各个服务详细的sw）

 

到此，在springboot中集成sw，与在springcloud微服务中集成sw的方法与实现就完成了。

至于sw中其他注解与更细致的操作，可以访问sw官网或者看其他的博客，这里就不重复描述了。