开发者社区> 攻城狮Chova> 正文
阿里云
为了无法计算的价值
打开APP
阿里云APP内打开

SpringBoot整合Swagger管理API接口详解

简介: 本文详细分析了如何在SpringBoot框架的项目中使用Swagger管理API接口,解决前后端分离项目中的接口文档难以有效管理的问题。在使用Swagger之前,介绍了Swagger相关的概念,分析了传统API文档管理的痛点,提出了Swagger工具使用的优点。详细说明了SpringBoot整合Swagger管理API接口文档的方式,主要介绍了Swagger在SpringBoot项目以及微服务架构项目中的应用。
+关注继续查看

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实现,以项目类型跳转到不同的接口文档
使用Zuul+Swagger实现微服务整个API接口文档的管理
  • 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文档注解                                        

版权声明:本文内容由阿里云实名注册用户自发贡献,版权归原作者所有,阿里云开发者社区不拥有其著作权,亦不承担相应法律责任。具体规则请查看《阿里云开发者社区用户服务协议》和《阿里云开发者社区知识产权保护指引》。如果您发现本社区中有涉嫌抄袭的内容,填写侵权投诉表单进行举报,一经查实,本社区将立刻删除涉嫌侵权内容。

相关文章
SpringBoot学习笔记-16:第十六章-SpringBoot 与监控管理
SpringBoot学习笔记-16:第十六章-SpringBoot 与监控管理
46 0
Springboot 返回数据提示语 国际化 (AOP实现)
Springboot 返回数据提示语 国际化 (AOP实现)
196 0
Springboot+Mybatis+Shiro实现角色权限管理
shiro是一个权限框架,具体的使用可以查看其官网 官网地址:https://shiro.apache.org/Shiro是Apache下的一个开源项目,我们称之为Apache Shiro。
1838 0
SpringBoot+mybatis+springsecurity实现用户角色数据库管理
SpringSecurity是专门针对基于Spring项目的安全框架,充分利用了依赖注入和AOP来实现安全管控。在很多大型企业级系统中权限是最核心的部分,一个系统的好与坏全都在于权限管控是否灵活,是否颗粒化。
3940 0
SpringBoot+Redis实现Session数据共享
使用SpringBoot+Redis实现Session数据共享。
1861 0
【IntelliJ IDEA】spring boot项目在idea实现自动部署
转载参考自:https://www.cnblogs.com/winner-0715/p/6666579.html   spring-boot-devtools是一个为开发者服务的一个模块,其中最重要的功能就是自动应用代码更改到最新的App上面去。
2364 0
Springboot和Spring Session实现session共享
HttpSession是通过Servlet容器创建和管理的,像Tomcat/Jetty都是保存在内存中的。而如果我们把web服务器搭建成分布式的集群,然后利用LVS或Nginx做负载均衡,那么来自同一用户的Http请求将有可能被分发到两个不同的web站点中去。
1840 0
SpringBoot SpringMVC实现文件下载
SpringBoot SpringMVC实现文件下载 @RequestMapping(value = "/download", method = RequestMethod.
993 0
SpringBoot实现文件上传下载的功能
SpringBoot我们大多数的时候是当做服务提供者来使用的,但是在一些场景中还是要用到一些文件上传下载这种"非常规"操作的。那么怎么在SpringBoot中实现文件的上传下载功能呢?想象一些我们在SpringMVC中是怎么做的。
3612 0
+关注
攻城狮Chova
一位有自我修养的攻城狮。 2006年《时代》周刊年度人物, 2008年感动中国组委会特别奖获得者。 专注分享技术干货,面试经验和攻城狮故事~ 欢迎点赞关注支持,是我持续进步的动力!
文章
问答
文章排行榜
最热
最新
相关电子书
更多
Java Spring Boot开发实战系列课程【第15讲】:Spring Boot 2.0 API与Spring REST Docs实战
立即下载
阿里云 API 精选手册(Alibaba Cloud API Playbook)
立即下载
Spring Boot2.0实战Redis分布式缓存
立即下载