微服务篇-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> <!-- SpringBoot整合Web组件 --> <dependency> <groupId>org.springframework.boot</groupId> <artifactId>spring-boot-starter-web</artifactId> </dependency> <!-- SpringBoot整合eureka客户端 --> <dependency> <groupId>org.springframework.cloud</groupId> <artifactId>spring-cloud-starter-netflix-eureka-client</artifactId> </dependency> <!-- swagger2 --> <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
| @Configuration @EnableSwagger2 public class SwaggerConfig { @Bean public Docket createRestApi() { return new Docket(DocumentationType.SWAGGER_2).apiInfo(apiInfo()).select() // api扫包 .apis(RequestHandlerSelectors.basePackage("com.ittcf.api")).paths(PathSelectors.any()).build(); } private ApiInfo apiInfo() { return new ApiInfoBuilder().title("") .termsOfServiceUrl("http://www.ittcf.com") // .contact(contact) .version("1.0").build(); } } |
访问地址:http://localhost:8060/swagger-ui.html#/swagger-controller
Zuul整合Swagger管理微服务所有API
用户和订单引入Maven依赖
| <!-- 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: 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依赖信息
| <!-- actuator监控中心 --> <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读取
本文部分素材转载自蚂蚁课堂