SpringCloud Zuul网关整合Swagger

版权声明：本文为博主原创文章，转载请注明出处 浅然的专栏 https://blog.csdn.net/w_linux/article/details/84795526

一、关于Swagger

Swagger能成为最受欢迎的REST APIs文档生成工具之一，有以下几个原因：

• Swagger 可以生成一个具有互动性的API控制台，开发者可以用来快速学习和尝试API。
• Swagger 可以生成客户端SDK代码用于各种不同的平台上的实现。
• Swagger 文件可以在许多不同的平台上从代码注释中自动生成。
• Swagger 有一个强大的社区，里面有许多强悍的贡献者

---

二、该篇博客使用技术版本

springcloud：Dalston.SR5

springboot：1.5.9.RELEASE

springfox-swagger-ui：2.7.0

pringfox-swagger2：2.7.0

zuul-core：1.3.0

---

三、开发实现

1、在总依赖中添加swagger相关依赖(因为多处地方会使用)

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

2、在网关服务下创建swagger

首先网关路由先配置好，如下

zuul:
  host:
    connect-timeout-millis: 3000
    socket-timeout-millis: 3000
  #路由规则
  routes:
    api-user:
      path: /api/user/**
      serviceId: wc-client-user
      #防止网关转发请求后session失效
      sensitiveHeaders: "*"
    api-search:
      path: /api/search/**
      serviceId: wc-client-search
      sensitiveHeaders: "*"

这里主要创建DocumentationConfig和SwaggerConfig，目录如下

DocumentationConfig.java

/**
 * 资源文档配置类
 */
@Component
@Primary
public class DocumentationConfig implements SwaggerResourcesProvider{

    @Override
    public List<SwaggerResource> get() {
        List resources = new ArrayList<>();
        resources.add(swaggerResource("搜索服务接口", "/api/search/v2/api-docs", "1.0"));// /api/search/是网关路由，/v2/api-docs是swagger中的
        resources.add(swaggerResource("用户服务接口", "/api/user/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;
    }

}

SwaggerConfig.java

/**
 * swagger配置
 */
@Configuration
@EnableSwagger2
public class SwaggerConfig {

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

    private ApiInfo apiInfo() {
        return new ApiInfoBuilder()
                .title("WingCloud")
                .description("WingCloud")
                .termsOfServiceUrl("http://localhost:8080")//网关端口
                .version("1.0")
                .build();
    }

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

}

3、在网关启动类上加上@EnableSwagger2注解

4、在client服务内的controller中进行注明

笔者这里以user服务为例

如下在类上添加@Api，在方法上添加@ApiOperation，当然还有其他注解，读者可自行百度/谷歌

/**
 * 用户请求处理控制器
 */
@Api("用户管理接口")
@RestController
public class UserController extends BaseController {

    @Autowired
    private IUserService userService;

    /**
     * 用户登录
     * @param request
     * @param result
     * @param req
     * @return
     */
    @ApiOperation(value = "/login",notes = "登录接口")
    @RequestMapping("/login")
    public SingleResult<TokenResponse> login(@Valid @RequestBody LoginRequest request, BindingResult result,HttpServletRequest req){
        //必须要调用validate方法才能实现输入参数的合法性校验
        System.out.println("-------------test-----------");
        validate(result);
        return userService.login(request,req);
    }
}

5、在client服务中添加Swagger配置

如下图目录

SwaggerConfig.java

/**
 * swagger配置
 */
@EnableSwagger2
@Configuration
public class SwaggerConfig {

    @Bean
    public Docket createRestApi() {
        return new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(apiInfo())
                .select()
                .apis(RequestHandlerSelectors.basePackage("top.wingcloud.controller"))//过滤的路径
                .apis(RequestHandlerSelectors.withClassAnnotation(Api.class))
                .apis(RequestHandlerSelectors.withMethodAnnotation(ApiOperation.class))
                .paths(PathSelectors.any())
                .build();
    }

    private ApiInfo apiInfo() {
        return new ApiInfoBuilder()
                .title("wc-client-user")
                .description("接口文档说明")
                .contact(new Contact("浅然", "", "[email protected]"))
                .version("2.0")
                .build();
    }
}

ok，配置整合完成后，启动相应的服务，然后进入http://localhost:8080/swagger-ui.html即可看到如下界面