原创作者：田超凡（程序员田宝宝）
版权所有，引用请注明原作者，严禁复制转载
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读取
本文部分素材转载自蚂蚁课堂