Swagger2 API接口管理

随着微服务架构体系的发展和应用， 为了前后端能够更好的集成与对接，同时为了项目的方便交付，每个项目都需要提供相应的API文档。
来源：PC端、微信端、H5端、移动端（安卓和IOS端）
对API文档进行更新的时候，需要通知前端开发人员，导致文档更新交流不及时；
API接口返回信息不明确

大公司中肯定会有专门文档服务器对接口文档进行更新。

缺乏在线接口测试，通常需要使用相应的API测试工具，比如postman、SoapUI等
接口文档太多，不便于管理
为了解决传统API接口文档维护的问题，为了方便进行测试后台Restful接口并实现动态的更新，因而引入Swagger接口工具。

1. 功能丰富：支持多种注解，自动生成接口文档界面，支持在界面测试API接口功能；
2. 及时更新：开发过程中花一点写注释的时间，就可以及时的更新API文档，省心省力；
3. 整合简单：通过添加pom依赖和简单配置，内嵌于应用中就可同时发布API接口文档界面，不需要部署独立服务。

整合springboot

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

@Configuration
@EnableSwagger2
publicclass SwaggerConfig {
 
  @Bean
  public Docket createRestApi() {
     returnnew Docket(DocumentationType.SWAGGER_2).apiInfo(apiInfo()).select()
          // api扫包范围
          .apis(RequestHandlerSelectors.basePackage("com.XXXX.api")).paths(PathSelectors.any()).build();
  }
// 创建api文档信息
  private ApiInfo apiInfo() {
     returnnew ApiInfoBuilder().title("XXXX-title")
                                .description("XXXX-相关描述")
          .termsOfServiceUrl("http://www.XXXX.com")//官方网址
          // .contact(contact)
          .version("1.0").build();
  }
}

swagger配置

####swagger相关配置
swagger:
  base-package: com.XXXX.service
  title: 服务title
  description: 服务description
  version: 1.1
  terms-of-service-url: www.XXXX.com
  contact:
     name: 旭出东方
     email: 834722772@qq.com

API 接口编写

@RestController
@RequestMapping("api")
@Api("swaggerDemoController相关的api")
public class SwaggerDemoController {

  private static final Logger logger = LoggerFactory.getLogger(SwaggerDemoController.class);
  
  @ApiOperation(value = "根据id查询学生信息", notes = "查询数据库中某个的学生信息")
  @ApiImplicitParam(name = "id", value = "学生ID", paramType = "path", required = true, dataType = "Integer")
  @RequestMapping(value = "/{id}", method = RequestMethod.GET)
  public String getStudent(@PathVariable int id) {
    logger.info("开始查询某个学生信息");
    return "success";
  }
}
 

Zuul整合Swagger管理微服务所有API

在我们的微服务中，Swagger是每个服务（会员服务、订单服务、支付服务）进行集成
如何将这个微服务中的Swagger进行合成，同一台服务器上

1. 使用Zuul+Swagger实现管理整个微服务API文档。
2. 使用Nginx+Swagger以项目不同区分条转不同的接口文档

Springboot支持对Swagger管理，只需要Zuul网关添加对应服务Swagger文档即可

服务端配置

<!-- swagger-spring-boot -->
    <dependency>
      <groupId>com.spring4all</groupId>
      <artifactId>swagger-spring-boot-starter</artifactId>
      <version>1.7.0.RELEASE</version>
    </dependency>

application.yml配置

Api接口扫描范围
####swagger相关配置
swagger:
  base-package: com.XXXX.service
  title: XXXX-title
  description: XXXX-description
  version: 1.0
  terms-of-service-url: www.XXXX.com
  contact:
     name: xuchudongfang
     email: 834722772@qq.com

项目启动引入开启生成文档
@EnableSwagger2Doc

ZuulGateway网关

引入依赖

<dependency>
  <groupId>com.spring4all</groupId>
  <artifactId>swagger-spring-boot-starter</artifactId>
  <version>1.7.0.RELEASE</version>
</dependency>

@SpringBootApplication
@EnableEurekaClient
@EnableZuulProxy
@EnableSwagger2Doc
public class AppGateWay {
 
  // @EnableZuulProxy 开启网关代理
 
  publicstaticvoid main(String[] args) {
    SpringApplication.run(AppGateWay.class, args);
  }
 
  // zuul配置能够使用config实现实时更新
  @RefreshScope
  @ConfigurationProperties("zuul")
  public ZuulProperties zuulProperties() {
    return new ZuulProperties();
  }
 
  // 添加文档来源
  @Component
  @Primary
  class DocumentationConfig implements SwaggerResourcesProvider {
    @Override
    public List<SwaggerResource> get() {
       Listresources = new ArrayList<>();
       // app-itmayiedu-order
       resources.add(swaggerResource("app-member", "/api-member/v2/api-docs", "2.0"));
       resources.add(swaggerResource("app-order", "/api-order/v2/api-docs", "2.0"));
       returnresources;
    }
 
    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:
  routes:
     api-a:
       ### 以 /api-member/访问转发到会员服务
       path: /api-member/**
       serviceId: app-member
     api-b:
       ### 以 /api-order/访问转发到订单服务
       path: /api-order/**
       serviceId: app-order