微服务篇-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读取

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