spring cloud整合swagger,通过zuul路由

spring cloud整合swagger,通过zuul路由

---

写在前面：开发中项目使用swagger做API管理，所有的请求通过zuul路由。此篇博客以博主实际开发中的架构为参考。

• pom引入swagger jar包

    <dependency>
      <groupId>io.springfox</groupId>
      <artifactId>springfox-swagger2</artifactId>
    </dependency>

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

• 将swagger配置类放到配置中心

import org.springframework.boot.bind.RelaxedPropertyResolver;
import org.springframework.context.EnvironmentAware;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import org.springframework.core.env.Environment;
import org.springframework.web.servlet.config.annotation.ResourceHandlerRegistry;
import org.springframework.web.servlet.config.annotation.WebMvcConfigurerAdapter;
import springfox.documentation.builders.ApiInfoBuilder;
import springfox.documentation.builders.PathSelectors;
import springfox.documentation.builders.RequestHandlerSelectors;
import springfox.documentation.service.ApiInfo;
import springfox.documentation.spi.DocumentationType;
import springfox.documentation.spring.web.plugins.Docket;
import springfox.documentation.swagger2.annotations.EnableSwagger2;

@Configuration
@EnableSwagger2
public class SwaggerConfiguration extends WebMvcConfigurerAdapter implements EnvironmentAware {
    private String basePackage;
    private String creatName;
    private String serviceName;
    private RelaxedPropertyResolver propertyResolver;
    private String description;

    public SwaggerConfiguration() {
    }

    public void addResourceHandlers(ResourceHandlerRegistry registry) {
        registry.addResourceHandler(new String[]{"swagger-ui.html"}).addResourceLocations(new String[]{"classpath:/META-INF/resources/"});
        registry.addResourceHandler(new String[]{"/webjars*"}).addResourceLocations(new String[]{"classpath:/META-INF/resources/webjars/"});
    }

    @Bean
    public Docket createRestApi() {
        return (new Docket(DocumentationType.SWAGGER_2)).apiInfo(this.apiInfo()).select().apis(RequestHandlerSelectors.basePackage(this.basePackage)).paths(PathSelectors.any()).build();
    }

    private ApiInfo apiInfo() {
        return (new ApiInfoBuilder()).title(this.serviceName + " Restful APIs").description(this.description).contact(this.creatName).version("1.0").build();
    }

    public void setEnvironment(Environment environment) {
        this.propertyResolver = new RelaxedPropertyResolver(environment, (String)null);
        this.basePackage = this.propertyResolver.getProperty("swagger.basepackage");
        this.creatName = this.propertyResolver.getProperty("swagger.service.developer");
        this.serviceName = this.propertyResolver.getProperty("swagger.service.name");
        this.description = this.propertyResolver.getProperty("swagger.service.description");
    }
}

• 配置application.yml文件

swagger:
    basepackage: com.sendinfo.product.api #扫描api包路径
    service:
        name: sendinfo product #api名称
        description: 产品中心 #api描述
        developer: admin #api开发

• 访问路径
  localhost+端口+模块名+swagger-ui.html
  swagger会自动根据springmvc的注解生成对应api
  如：

import com.xiaoleilu.hutool.util.StrUtil;
import io.swagger.annotations.ApiImplicitParam;
import io.swagger.annotations.ApiImplicitParams;
import io.swagger.annotations.ApiParam;
import org.springframework.beans.factory.annotation.Autowired;
import org.springframework.web.bind.annotation.GetMapping;
import org.springframework.web.bind.annotation.RequestMapping;
import org.springframework.web.bind.annotation.RestController;
import tk.mybatis.mapper.entity.Example;

@RestController
@RequestMapping("/api/product")
public class ComboApi {

    @Autowired
    private ComboInfoBiz comboInfoBiz;

    @GetMapping(value = "/combos")
    public Response listComboInfo(
            @ApiParam(value = "当前页", required = true) @RequestParam Integer currPage,
            @ApiParam(value = "每页显示多少条数据", required = true) @RequestParam Integer pageSize) {
        Example example = new Example(ComboInfo.class);
        example.createCriteria().andEqualTo("enabled", SysParamConstants.ENABLED_YES);
        Page page = new Page(0, pageSize);
        page.setPage(currPage);
        page.setSort("createTime");
        return Response.ApiSuccess(comboInfoBiz.page(example, page));
    }
}

注：
使用@RequestParam注解才能获取到参数

几个常用的swagger注解：

@ApiModel()用于类 ；表示对类进行说明，用于参数用实体类接收
value–表示对象名
description–描述
都可省略
@ApiModelProperty()用于方法，字段； 表示对model属性的说明或者数据操作更改
value–字段说明
name–重写属性名字
dataType–重写属性类型
required–是否必填
example–举例说明
hidden–隐藏
@ApiIgnore()用于类或者方法上，可以不被swagger显示在页面上
@ApiParam() 用于方法，参数，字段说明；表示对参数的添加元数据（说明或是否必填等）
name–参数名
value–参数说明
required–是否必填
@ApiResponses 用于方法上，对响应的描述
@ApiResponse用在@ApiResponses 中
@ApiOperation 用在方法上，对方法的描述

---

给swagger添加描述
方法上：

类上：

页面：