“ 本文向大家介绍Spring Boot与Swagger2的搭配使用,包括Swagger2的概念、注释以及常规的使用等。”
章节目录- 环境
- 简介
- 场景
- 使用
- 注释
- 概要/分组/鉴权
- 总结
01
—
环境
Spring Boot v2.4.1, Spring v5.3.1,IntelliJ IDEA v2019.3.5,Maven v3.5, JDK 1.8 , MySQL 5.6, Swagger23.0.0本文中的示例代码均可在GitHub上获取,地址是:https://github.com/lovebaylong/hessian-demo-client02
—
简介
Swagger是一个在线的API文档生成工具,它有两个大版本,分别是Swagger1和Swagger2,目前基本都是使用Swagger2。我们体验也是使用Swagger2版本。它不仅能动态生成接口文档还提供了测试功能,对前后端分离的开发比较友好。后端人员也不需要为前端人员写接口文档,而且它是实时生效,避免接口与文档不同步的问题。Swagger2目前最新的版本是3.0.0.0,我们今天主要讲它与Spring Boot的整合,其他的环境请自行了解。Spring Boot应用程序可以使用swagger 1.2, 2.0 和3.0版本,当然最新的最香嘛!先上几张实际运行后的效果图,示例如下:03
—
场景
建议采用前后端开发模式的团队内部使用,不建议对外,对外还是建议使用独立的在线文档或是线下文档的方式,或是单独提供api官网。另外由于Swagger需要通过注释等方式侵入到业务代码里,所以会导致你的业务代码里多出很多与业务功能不相关的注释与代码等。特别是接口功能、参数、响应等越复杂要为些标注的注释与描述就越多,最后甚至Swagger相关的代码量会超过你接口的代码量。考虑如下示例:04
—
使用
引入Maven依赖,因为我们直接使用Spring Boot,所以直接引入它提供的starter就可以了:<dependency> <groupId>io.springfoxgroupId> <artifactId>springfox-boot-starterartifactId> <version>3.0.0version>dependency>
该starter自动为我们引入以下依赖,全景如下:
<dependency> <groupId>io.springfoxgroupId> <artifactId>springfox-swagger2artifactId> <version>3.0.0version>dependency><dependency> <groupId>io.springfoxgroupId> <artifactId>springfox-swagger-uiartifactId> <version>3.0.0version>dependency>
这两个依赖自动为我们引入了以下依赖,全景如下:
05
—
注释
在Spring Boot里,我们主要通过各种注释来实现开放api的文档输出,swagger 3系列的注释由两部分组合,除了两个启动注释@EnableOpenApi和@EnableSwagger2外,其他由原来swagger-annotations-1.5.xx.jar和和swagger-annotations-2.1.x.jar提供,swagger-annotations-2.1.x.jar是由3.0版本中的oas组件包含引入的。两者提供的注释列表如下表所示:@Configuration//@EnableSwagger //Enable swagger 1.2 spec//@EnableSwagger2 //Enable swagger 2.0 spec@EnableOpenApi //Enable open api 3.0.3 specpublic class SwaggerConfig {......}
2、@Api用于声明当前对象是Swagger的资源,需要为该对象生成API文档,这个注释只能标注在类、接口(包括注释@interface)或枚举上。
@Api(value = "用户管理相关接口", tags = {"用户"})public class UserOpenApiController {......}
只要在类上加上该注释,则里面所有的public方法都默认会输出文档。即不在方法上增加@ApiOperation注释也一样。3、@ApiOperation表明这是一个具体的api方法或操作,为该方法生成API文档,生成测试套件等。它主要用于方法上,当然也能标注在类、接口(包括注释@interface)或枚举上,但是没啥用。
@ApiOperation(value = "根据用户编号获取用户详情,返回单个Json对象")public JsonNode detail(@RequestParam(value = "id") Long id) { return userService.detail(id);}
4、@ApiParam主要用于接口参数说明,可标注在方法、属性、参数上。
public JsonNode detail( @RequestParam(value = "id") @ApiParam(value = "用户编号", required = true) Long id) {...}
效果:
@ApiResponses(value = { @ApiResponse(responseCode = "401", description = "未经授权"), @ApiResponse(responseCode = "403", description = "权限不足"), @ApiResponse(responseCode = "404", description = "用户不存在"), @ApiResponse(responseCode = "400", description = "用户已冻结")})
1.5版本的写法:
@ApiResponses(value = { @ApiResponse(code = 401, message = "未经授权"), @ApiResponse(code = 403, message = "权限不足"), @ApiResponse(code = 404, message = "用户不存在"), @ApiResponse(code = 400, message = "用户已冻结")})
效果如下:
@ApiOperation(value = "根据用户编号获取用户详情,返回单个Json对象", notes = "数据来源于Hessian接口", authorizations = @Authorization(value = "demoClient_auth", scopes = {@AuthorizationScope(scope = "read:user", description = "用户只读")}))
如果scopes只有一个时不需要{}。增加了授权认证的接口会在UI上标识如下:
@ApiOperation(value = "根据用户编号获取用户详情,返回单个Json对象", notes = "数据来源于Hessian接口", response = ResponseEntity.class, responseHeaders = {@ResponseHeader(name = "header1", response = String.class)}, authorizations = @Authorization(value = "token", scopes = {@AuthorizationScope(scope = "read:user", description = "用户只读")}))
效果:
@ApiModel(description = "用户信息")public class UserPojo {}
效果如下:
@ApiModelProperty(value = "用户名称", required = true)private String name;@ApiModelProperty(value = "用户年龄", required = true)private Integer age;
效果如下:
![f897487608eecc4ef0a7eb40bf0f192e.png](https://img-blog.csdnimg.cn/img_convert/f897487608eecc4ef0a7eb40bf0f192e.png)
public JsonNode add(UserPojo user) { ...}public JsonNode add(@ModelAttribute UserPojo user) { ...}
06
—
概要/分组/鉴权
1、 概要在接口文档的UI页面上,会显示一些 默认的概要信息,如下:07
—
总结
本文针对Spring Boot + Swagger 输出在线文档,还有很多的注释与用法还有待大家去挖掘、发现与学习,大家赶紧行动起来吧!
推荐阅读 |
---|
Spring Boot + Hessian实战 Spring Cloud 构建微服务架构-01 IntelliJ IDEA + Git Push 入门 WebSocket基础学习 Java 8 Streams基础详解 Java Bean验证基础详解 Spring Boot - 创建一个简单Web应用Spring AOP 学习 Spring 核心注释 之 原型注释 Spring 注释系列 之 Scheduling注释 Spring 注释系列 之 Spring Boot注释 Spring 核心注释 之 Web注释 Spring 核心注释 之 上下文配置注释详解 Spring 核心注释 之 依赖注入注释详解 |
![85412d98c49ce4dcf46032f2487e84b3.png](https://img-blog.csdnimg.cn/img_convert/85412d98c49ce4dcf46032f2487e84b3.png)
![42741abd5583cc3a963b2b7e4be1b6a5.gif](https://img-blog.csdnimg.cn/img_convert/42741abd5583cc3a963b2b7e4be1b6a5.gif)