微服务篇-C 深入理解第一代微服务（SpringCloud）_VII 深入理解Swagger接口文档可视化管理工具

原创作者：田超凡（程序员田宝宝）

Part 1 理论部分

1 传统API接口文档存在的问题？

1 对API接口文档进行更新的时候，需要及时将变化通知前端开发人员，否则API接口文档的更新可能会因为通知不及时导致联调时出现问题。

2 API接口返回的响应信息描述不够清晰明确。

3 缺乏在线API接口测试的功能，通常需要使用第三方的API接口测试工具，比如Postman，SoapUI等。

4 API接口文档太多，不利于统一管理。

5 大公司肯定会有专门的API接口文档服务器来对API接口文档进行更新和维护，但是对于一些中小型公司而言，单独搭建API接口文档服务器的成本太高。

2 什么是Swagger？

为了解决传统API接口文档维护的问题，方便测试后台Restful接口并实现动态的API接口文档更新，因此引入Swagger作为API接口文档可视化管理工具。

3 Swagger的优点有哪些？

1 功能丰富：支持多种注解，自动生成接口文档界面，支持在界面上测试API接口的功能。

2 及时更新：在开发工程中只需要花一点写注释的时间，就可以及时更新API接口文档，省时省力。

3 整合简单：通过添加pom依赖和简单配置，内嵌于应用中就可随应用发布的时候同时发布API接口文档管理界面，不需要部署单独的服务。

Part 2 实践部分

Swagger API接口管理

随着微服务架构体系的发展和应用，为了前后端能够更好的集成与对接，同时为了项目的方便交付，每个项目都需要提供相应的API文档。

来源：PC端、微信端、H5端、移动端（安卓和IOS端）

Swagger 2.0 集成配置

Maven依赖信息

|---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| <parent> <groupId>org.springframework.boot</groupId> <artifactId>spring-boot-starter-parent</artifactId> <version>2.0.1.RELEASE</version> </parent>  <dependencyManagement> <dependencies> <dependency> <groupId>org.springframework.cloud</groupId> <artifactId>spring-cloud-dependencies</artifactId> <version>Finchley.M7</version> <type>++pom++ </type> <scope>import</scope> </dependency> </dependencies> </dependencyManagement> <dependencies>  <dependency> <groupId>org.springframework.boot</groupId> <artifactId>spring-boot-starter-web</artifactId> </dependency>  <dependency> <groupId>org.springframework.cloud</groupId> <artifactId>spring-cloud-starter-++netflix++ -++eureka++-client</artifactId> </dependency>  <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> </dependencies>  <repositories> <repository> <id>spring-milestones</id> <name>Spring Milestones</name> <url>https://repo.spring.io/libs-milestone\</url> <snapshots> <enabled>false</enabled> </snapshots> </repository> </repositories> |

SwaggerConfig

访问地址:http://localhost:8060/swagger-ui.html#/swagger-controller

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

用户和订单引入Maven依赖

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

application.yml配置

Api接口扫描范围

|--------------------------------------|
| swagger: base-package: com.ittcf.api |

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

@EnableSwagger2Doc

ZuulGateway网关

|-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| @SpringBootApplication @EnableEurekaClient @EnableZuulProxy @EnableSwagger2Doc public class AppGateWay { // @EnableZuulProxy 开启网关代理 public static void 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() { ++List++ resources = new ArrayList<>(); // ++app++ -++ittcf++-order ++resources++ ++.add(swaggerResource(++ ++"app-ittcf-member"++ ++,++ ++"/api-member/v2/api-docs"++ ++,++ ++"2.0"++ ++))++ ; ++resources++ ++.add(swaggerResource(++ ++"app-ittcf-order"++ ++,++ ++"/api-order/v2/api-docs"++ ++,++ ++"2.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; } } } |

Maven依赖信息

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

Actuator端点刷新数据

Maven依赖信息

|------------------------------------------------------------------------------------------------------------------------------------------------------------------|
|  <dependency> <groupId>org.springframework.boot</groupId> <artifactId>spring-boot-starter-actuator</artifactId> </dependency> |

bootstrap.yml新增

开启监控断点

|-----------------------------------------------------|
| management: endpoints: web: exposure: include: "*" |

生效前提

在需要刷新的Bean上添加@RefreshScope注解。

|-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| @RestController // @SpringBootApplication @RefreshScope public class ConfigClientController { http://127.0.0.1:8882/actuator/refresh @Value("${ittcfInfo}") private String ittcfInfo; |

当配置更改时，标有@RefreshScope的Bean将得到特殊处理来生效配置

手动刷新接口

Post请求手动刷新

http://127.0.0.1:8882/actuator/refresh 启动刷新器从config server读取

本文部分素材转载自蚂蚁课堂