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

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

相关推荐
RainbowSea11 分钟前
跨域问题(Allow CORS)解决(3 种方法)
java·spring boot·后端
掘金-我是哪吒13 分钟前
分布式微服务系统架构第155集:JavaPlus技术文档平台日更-Java线程池实现原理
java·分布式·微服务·云原生·架构
RainbowSea16 分钟前
问题 1:MyBatis-plus-3.5.9 的分页功能修复
java·spring boot·mybatis
前端 贾公子19 分钟前
monorepo + Turborepo --- 开发应用程序
java·前端·javascript
不学会Ⅳ1 小时前
Mac M芯片搭建jdk源码环境(jdk24)
java·开发语言·macos
虫小宝1 小时前
高佣金返利平台监控体系建设:APM、链路追踪与佣金异常预警系统技术实现
java
sniper_fandc2 小时前
SpringBoot系列—入门
java·spring boot·后端
代码的余温3 小时前
Maven引入第三方JAR包实战指南
java·maven·jar
pianmian16 小时前
类(JavaBean类)和对象
java
我叫小白菜7 小时前
【Java_EE】单例模式、阻塞队列、线程池、定时器
java·开发语言