微服务中Swagger2结合Zuul搭建Restful API文档（一）

本文章可将swagger配置类提取到公共服务模块，不需要在每个业务模块中编写swagger配置类，并通过Zuul网关将整个系统的API文档整合在同一个页面上，通过Zuul的端口访问即可。

Swagger2配置

在父级pom.xml文件中引入依赖：

  <properties>
        ······
        <swagger2-version>2.7.0</swagger2-version>
  </properties>
  <dependencies>
		······
        <!--swagger2 集成-->
        <dependency>
            <groupId>io.springfox</groupId>
            <artifactId>springfox-swagger2</artifactId>
            <version>${swagger2-version}</version>
        </dependency>

        <dependency>
            <groupId>io.springfox</groupId>
            <artifactId>springfox-swagger-ui</artifactId>
            <version>${swagger2-version}</version>
        </dependency>
  
   </dependencies>

在公共服务模块cloud-common中编写swagger配置类SwaggerConfig：

@Configuration
@EnableSwagger2
@ComponentScan(basePackages = {"com"}) // 扫描路径
public class SwaggerConfig {

    @Bean
    public Docket createRestApi() {
        return new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(apiInfo())
                .select()
                .apis(RequestHandlerSelectors.basePackage("com"))
                .apis(RequestHandlerSelectors.withClassAnnotation(Api.class))
                .apis(RequestHandlerSelectors.withMethodAnnotation(ApiOperation.class))
                .paths(PathSelectors.any())
                .build();
    }

    private ApiInfo apiInfo() {
        return new ApiInfoBuilder()
                .title("智慧水务综合管理平台")
                .description("智慧水务综合管理平台接口文档说明")
                .version("1.0")
                .build();
    }

    @Bean
    UiConfiguration uiConfig() {
        return new UiConfiguration(null, "list", "alpha", "schema",
                UiConfiguration.Constants.DEFAULT_SUBMIT_METHODS, false, true, 60000L);
    }
}

使用Swagger

在用户管理模块cloud-user和巡查管理模块cloud-patrol中使用Swagger，需要分别在它们的pom.xml中引入公共服务模块cloud-common：

  		<dependency>
			<groupId>com.example</groupId>
			<artifactId>cloud-common</artifactId>
			<version>1.0.0</version>
		</dependency>

接着分别在cloud-user和cloud-patrol的启动了中引入@ComponentScan(basePackages={“com.config”})注解，该注解可以在服务启动的时候去加载cloud-common中com.config目录下的Swagger配置类：
cloud-user

@SpringBootApplication
@ComponentScan(basePackages={"com.config"})//引入swagger2
public class CloudUserApplication {
	public static void main(String[] args) {
		SpringApplication.run(CloudUserApplication.class, args);
	}
}

cloud-patrol

@SpringBootApplication
@ComponentScan(basePackages={"com.config"})//引入swagger2
public class CloudPatrolApplication {
	public static void main(String[] args) {
		SpringApplication.run(CloudPatrolApplication.class, args);
	}
}

然后在相应模块的controller控制类中使用swagger注解，cloud-patrol模块中PatrolController.java中代码如下：

@RestController
@CrossOrigin
@RequestMapping("/patrol")
@Api(tags = "巡查管理系统", description = "巡查管理系统模块相关接口")
public class PatrolController {

    @RequestMapping(method = RequestMethod.POST)
    @ApiOperation(value="新增巡查记录", notes="根据Patrol对象创建巡查记录")
    @ApiImplicitParam(name = "patrol", value = "巡查记录实体patrol", required = true, dataType = "Patrol")
    public Result save(){
    	//此处省略service层
        return Result.InsertSuccess(null);
    }

}

cloud-user模块UserController.java代码略。

cloud-user和cloud-patrol模块端口分别为9002、9003，启动cloud-user和cloud-patrol模块，打开浏览器访问 http://localhost:9002/swagger-ui.html，http://localhost:9003/swagger-ui.html 可以看到如下界面：


至此已经实现给各业务模块形成在线API文档，通过对应业务模块的端口即可访问，但当业务模块大量增加的时候，API文档需要在不同访问地址中来回切换，这时就需要用到Zuul网关配合。

Swagger结合Zuul

网关模块cloud-zuul端口为8002，代码结构如下：

在application.yml中配置路由：

zuul:
  routes:
    cloud-user:
      path: /user/**
    cloud-patrol:
      path: /patrol/**

新建swagger配置类SwaggerConfig：

@Configuration
@EnableSwagger2
public class SwaggerConfig {

    @Bean
    public Docket createRestApi() {
        return new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(apiInfo());
    }

    private ApiInfo apiInfo() {
        return new ApiInfoBuilder()
                .title("智慧水务综合管理平台")
                .description("智慧水务综合管理平台接口文档说明")
                .termsOfServiceUrl("http://localhost:8002")
                .version("1.0")
                .build();
    }

    @Bean
    UiConfiguration uiConfig() {
        return new UiConfiguration(null, "list", "alpha", "schema",
                UiConfiguration.Constants.DEFAULT_SUBMIT_METHODS, false, true, 60000L);
    }
}

新建swagger文档资源配置类DocumentationConfig：

@Component
@Primary
public class DocumentationConfig implements SwaggerResourcesProvider {
    @Override
    public List<SwaggerResource> get() {
        List resources = new ArrayList<>();
        resources.add(swaggerResource("用户管理系统", "/user/v2/api-docs", "1.0"));
        resources.add(swaggerResource("巡查管理系统", "/patrol/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;
    }
}

启动cloud-user、cloud-patrol和cloud-zuul模块，打开浏览器访问 http://localhost:8002/swagger-ui.html可以看到如下界面：

通过下拉框进行切换子系统API文档，整合完毕。