写点什么

SpringBoot 整合 Swagger 管理 API 接口详解

发布于: 2021 年 05 月 13 日
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-ui2.创建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 实现,以项目类型跳转到不同的接口文档

使用 Zuul+Swagger 实现微服务整个 API 接口文档的管理
  • SpringBoot 中支持对 Swagger 进行管理,只需要在 Zuul 网关中添加对应服务的 Swagger 文档即可

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


在各个微服务的类中:1.在各个微服务中引入SpringBoot支持的Swagger依赖swagger-spring-boot-starter2.配置文件,可省略不写:(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-starter2.在Zuul网关类中创建SwaggerAPI文档的配置类逻辑方法 添加文档来源:resource.add(swaggerResource("文档名称","API接口文档","版本号"))3.在SwaggerAPI文档的配置类上标注@Component将配置类添加到容器中4.在Zuul网关类上标注@EnableSwagger2Doc开启Swagger文档注解
复制代码


发布于: 2021 年 05 月 13 日阅读数: 34
用户头像

一位攻城狮的自我修养 2021.04.06 加入

分享技术干货,面试题和攻城狮故事。 你的关注支持是我持续进步的最大动力! https://github.com/ChovaVea

评论

发布
暂无评论
SpringBoot整合Swagger管理API接口详解