SpringBoot整合Swagger管理API接口详解

Swagger概念

传统API文档管理缺点:

- 对API文档更新时需要通知前端人员,导致文档更新交流不及时,API接口返回信息不明确

- 缺乏在线接口测试,需要使用额外的API测试工具:postman,SoapUI

- 接口文档太多,不便于管理

为了解决传统API文档维护问题,方便进行测试后台RESTful接口并实现动态更新,引入Swagger接口工具

Swagger工具优点:

- 功能丰富: 支持多种注解,自动生成接口文档界面,支持在界面测试API接口功能

- 及时更新: 在开发工程中编写好注释,就可以及时更新API文档

- 整合简单: 通过添加pom.xml依赖和简单配置,内嵌于应用中就可同时发布API接口文档界面,不需要部署独立服务

整合Swagger生成API文档

springboot项目

1.引入Maven依赖springfox-swagger2和springfox-swagger-ui 2.创建SwaggerConfig类实现Swagger生成API文档逻辑: 生成API文档的扫包范围apis 创建API文档信息ApiInfoBuilder.title("文档标题").description("文档描述").termOfServiceUrl("网址Url").version("版本号").build() 3.在SwaggerConfig类上标注@EnableSwagger2注解开启Swagger功能 4.创建SwaggerController类,在类中创建API接口 5.在SwaggerController类上标注@Api("接口描述")注解作整体接口描述 6.在SwaggerController类里API接口上被标注@ApiOperation("具体接口描述")注解,标注@ApiImplicitParam(name="参数名称",value="参数值",required=true,dataType="参数类型") 7.注意:不要在API接口类上标注RequestMapping注解(这样会生成所有请求接口,没有可读性),根据相应的请求方式,标注@XxxMapping注解 8.创建启动类启动

微服务集群项目

在微服务项目中,Swagger是在每个服务进行集成的,需要将整个微服务中的Swagger进行合成到同一台服务器上:

- 使用Zuul+Swagger实现

- 使用Nginx+Swagger实现,以项目类型跳转到不同的接口文档

SpringBoot中支持对Swagger进行管理,只需要在Zuul网关中添加对应服务的Swagger文档即可

原理: 每个独立服务都会集成Swagger自动生成API文档,前端发送服务请求到Zuul网关,Zuul根据请求调用对应服务的Swagger查询API接口

在各个微服务的类中: 1.在各个微服务中引入SpringBoot支持的Swagger依赖swagger-spring-boot-starter 2.配置文件,可省略不写: (swagger.base-package=需要生成文档的包名) 3.在微服务的主类上标注@EnableSwagger2Doc文档注解,生成Swagger文档, 4.在微服务的主类上标注@Api("接口描述")注解作整体接口描述 5.在SwaggerController类里API接口上被标注@ApiOperation("具体接口描述")注解 6.标注@ApiImplicitParam(name="参数名称",value="参数值",required=true,dataType="参数类型") 在Zuul网关类中: 1.引入SpringBoot支持的Swagger依赖swagger-spring-boot-starter 2.在Zuul网关类中创建SwaggerAPI文档的配置类逻辑方法 添加文档来源:resource.add(swaggerResource("文档名称","API接口文档","版本号")) 3.在SwaggerAPI文档的配置类上标注@Component将配置类添加到容器中 4.在Zuul网关类上标注@EnableSwagger2Doc开启Swagger文档注解

API Spring Boot

版权声明：本文内容由网络用户投稿，版权归原作者所有，本站不拥有其著作权，亦不承担相应法律责任。如果您发现本站中有涉嫌抄袭或描述失实的内容，请联系我们jiasou666@gmail.com 处理，核实后本网站将在24小时内删除侵权内容。