第二章:Swagger2
目录
背景介绍
什么是Swagger2
常用注解
SpringBoot整合Swagger2
生产环境下屏蔽Swagger2
修改Swagger2配置类
修改application.yml
使用maven package打包测试
运行测试
背景介绍
在团队开发中,一个好的 API 文档不但可以减少大量的沟通成本,还可以帮助一位新人快速上手业务。传统的做法是由开发人员创建一份 RESTful API 文档来记录所有的接口细节,并在程序员之间代代相传。这种做法存在以下几个问题:
1)API 接口众多,细节复杂,需要考虑不同的HTTP请求类型、HTTP头部信息、HTTP请求内容等,想要高质量的完成这份文档需要耗费大量的精力;
2)难以维护。随着需求的变更和项目的优化、推进,接口的细节在不断地演变,接口描述文档也需要同步修订,可是文档和代码处于两个不同的媒介,除非有严格的管理机制,否则很容易出现文档、接口不一致的情况;
Swagger2 的出现就是为了从根本上解决上述问题。它作为一个规范和完整的框架,可以用于生成、描述、调用和可视化 RESTful 风格的 Web 服务:
接口文档在线自动生成,文档随接口变动实时更新,节省维护成本;
支持在线接口测试,不依赖第三方工具;
什么是Swagger2
Swagger2 是一个规范和完整的框架,用于生成、描述、调用和可视化Restful风格的web服务,现在我们使用spring boot 整合它。作用:
接口的文档在线自动生成;
功能测试;
常用注解
注解 | 描述 |
---|---|
@Api | 将类标记为 Swagger 资源。 |
@ApiImplicitParam | 表示 API 操作中的单个参数。 |
@ApiImplicitParams | 允许多个 ApiImplicitParam 对象列表的包装器。 |
@ApiModel | 提供有关 Swagger 模型的其他信息。 |
@ApiModelProperty | 添加和操作模型属性的数据。 |
@ApiOperation | 描述针对特定路径的操作或通常是 HTTP 方法。 |
@ApiParam | 为操作参数添加额外的元数据。 |
@ApiResponse | 描述操作的可能响应。 |
@ApiResponses | 允许多个 ApiResponse 对象列表的包装器。 |
@Authorization | 声明要在资源或操作上使用的授权方案。 |
@AuthorizationScope | 描述 OAuth2 授权范围。 |
SpringBoot整合Swagger2
导入依赖
<dependency><groupId>io.springfox</groupId><artifactId>springfox-swagger2</artifactId><version>2.9.2</version><exclusions><exclusion><artifactId>swagger-models</artifactId><groupId>io.swagger</groupId></exclusion></exclusions>
</dependency>
<dependency><groupId>com.github.xiaoymin</groupId><artifactId>swagger-bootstrap-ui</artifactId><version>1.8.5</version>
</dependency>
<!-- 使用1.5.22-->
<dependency><groupId>io.swagger</groupId><artifactId>swagger-models</artifactId><version>1.5.22</version>
</dependency>
创建Swagger配置类
@Configuration
//开启Swagger2
@EnableSwagger2
//配置生产环境下不可用 dev(开发)、test(测试)、prod(生产)
@Profile({"dev","test"})
public class Swagger2Configuration extends WebMvcConfigurationSupport {//api接口包扫描路径public static final StringSWAGGER_SCAN_BASE_PACKAGE = "com.lky.swagger2pro.controller";//指定当前Swagger API文档版本public static final String VERSION = "1.0.0";
/*** 创建API应用* apiInfo() 增加API相关信息* 通过select()函数返回一个ApiSelectorBuilder实例,用来控制哪些接口暴露给Swagger来展现,* 本例采用指定扫描的包路径来定义指定要建立API的目录。* @return*/@Beanpublic Docket createRestApi() {return new Docket(DocumentationType.SWAGGER_2)// 接口文档的基本信息.apiInfo(apiInfo()).select()// 方法需要有ApiOperation注解才能生存接口文档//.apis(RequestHandlerSelectors.basePackage(SWAGGER_SCAN_BASE_PACKAGE)).apis(RequestHandlerSelectors.withMethodAnnotation(ApiOperation.class))// 路径使用any风格.paths(PathSelectors.any()).build();}
/*** 创建该API的基本信息(这些基本信息会展现在文档页面中)* 访问地址:http://项目实际地址/doc.html* @return*/private ApiInfo apiInfo() {return new ApiInfoBuilder().title("SpringBoot中使用Swagger2构建RestFul APIs").description("测试系统")//.termsOfServiceUrl("http://www.**.com").version(VERSION).build();}
@Overrideprotected void addResourceHandlers(ResourceHandlerRegistry registry) {registry.addResourceHandler("doc.html").addResourceLocations("classpath:/META-INF/resources/");registry.addResourceHandler("/webjars/**").addResourceLocations("classpath:/META-INF/resources/webjars/");}
}
1) 完成以上配置之后,通过mybatis-generator生成model和mapper; 2) 创建IBookService及BookServiceImpl实现类; 3) 创建BookController
综合案例
@Api
@Api注解用在类上,说明该类的作用。可以标记一个Controller类做为swagger文档资源。
属性 | 说明 |
---|---|
value | url的路径值 |
tags | 如果设置这个值、value的值会被覆盖 |
produces | 返回的格式类型例如:"application/json, application/xml" |
consumes | 接收请求参数的类型例如:"application/json, application/xml" |
protocols | Possible values: http, https, ws, wss. |
authorizations | 高级特性认证时配置 |
案例演示
@RestController
@Api(value = "书本管理",tags = {"书本管理"}) //tags可以代替value属性
@RequestMapping("/book")
public class BookController {...
}
@ApiOperation
@ApiOperation注解用在方法上,说明方法的作用,每一个url资源的定义。
属性 | 说明 |
---|---|
value | url的路径值 |
tags | 如果设置这个值、value的值会被覆盖 |
produces | 返回的格式类型例如:"application/json, application/xml" |
consumes | 接收请求参数的类型例如:"application/json, application/xml" |
hidden | 是否在文档中显示 |
notes | 注释说明 |
response | 返回的对象 |
responseContainer | 这些对象是有效的 "List", "Set" or "Map".,其他无效 |
responseReference | 指定对响应类型的引用。指定的引用可以是本地的,也可以是远程的*将按原样使用,并覆盖任何指定的response()类 |
responseHeaders | 响应旁边提供的可能标题列表 |
httpMethod | "GET", "HEAD", "POST", "PUT", "DELETE", "OPTIONS" and "PATCH" |
code | http的状态码 默认 200 |
案例演示
@ApiOperation(value = "查询所有书本信息", notes = "查询返回所有书本信息集合",produces = "application/json")
@GetMapping(value="/queryAll")
public JsonResponseBody<List<Book>> queryAll(){try {return bookService.queryAll();} catch (Exception e) {e.printStackTrace();return new JsonResponseBody<>(500,e.getMessage());}
}
@ApiImplicitParam
@ApilmplicitParam 注解用来描述一个参数,可以配置参数的中文含义,也可以给参数设置默认值,这样在接口测试的时候可以避免手动输入;
属性 | 说明 |
---|---|
paramType | 参数放在哪个地方 |
name | 参数名称 |
value | 参数代表的含义 |
dataType | 参数类型 |
dataTypeClass | 参数类型 |
required | 是否必要 |
defaultValue | 参数的默认值 |
paramType
类型 | 作用 |
---|---|
path | 以地址的形式提交数据,用于restful接口。请求参数采用@PathVariable获取 |
query | 直接跟参数完成自动映射赋值。请求参数可采用@RequestParam获取 |
body | 以流的形式提交,仅支持POST。请求参数采用@RequestBody获取 |
header | 参数在request headers里边提交。请求参数采用@RequestHeader获取 |
form | 以form表单的形式提交,仅支持POST。 |
案例演示
@ApiOperation(value="查询单个书本信息",notes = "查询单个书本信息")
@ApiImplicitParam(value="书本ID",name="bookid",required = true,dataType = "String",defaultValue = "8f46b5018a6811e9a9c528d24413c293" )
@GetMapping("/querySingleBook")
public Book querySingleBook(String bookid){JsonResponseBody<Book> json = bookService.selectByPrimaryKey(bookid);return json.getData();
}
@ApiImplicitParams
@ApilmplicitParams 如果有多个参数,则需要使用多个 @ApilmplicitParam 注解来描述, 多个 @ApilmplicitParam 注解需要放在一个 @ApilmplicitParams 注解中;
案例演示
@ApiOperation(value = "新增书本信息", notes = "新增书本信息",produces = "application/json",consumes = "application/json")
@ApiImplicitParams({@ApiImplicitParam(name="bookname",value="书本名称",required = true,dataType = "String"),@ApiImplicitParam(name="price",value="书本价格",required = true,dataType = "Double"),@ApiImplicitParam(name="booktype",value="书本类型",required = true,dataType = "String")
})
@PostMapping("/addBook")
public JsonResponseBody<?> addBook(@RequestParam String bookname,@RequestParam Double price,@RequestParam String booktype){return bookService.insert(Book.builder().bookid(UUID.randomUUID().toString().replace("-","")).bookname(bookname).booktype(booktype).price(price).build());
}
@ApiModel和@ApiModelProperty
@ApiModel注解描述一个Model的信息(这种一般用在post创建的时候,使用@RequestBody这样的场景,请求参数无法使用 @ApiImplicitParam注解进行描述的时候;
@ApiModelProperty注解描述一个model的属性。
属性 | 说明 |
---|---|
value | 字段说明 |
name | 参数名称 |
dataType | 参数类型 |
hidden | 在文档中隐藏 |
required | 是否必要 |
example | 举例说明 |
notes | 注释说明 |
案例演示
Controller
@ApiOperation(value="修改书本信息",notes = "修改书本信息")
@PostMapping("/editBook")
public JsonResponseBody<?> editBook(@RequestBody Book book){return bookService.updateByPrimaryKey(book);
}
注意:在这里可以不使用@ApiImplicitParam标注Swagger中的参数信息,因为在这里的输入参数是实体对象,而在实体对象中已经使用@ApiModel和@ApiModelProperty注解进行了标识。
Book实体类
@Data
@Builder
@AllArgsConstructor
@NoArgsConstructor
@ApiModel(value="书本对象")
public class Book implements Serializable {
/*** 书本编号*/@ApiModelProperty(value="书本编号")private String bookid;
/*** 书本名称*/@ApiModelProperty(value="书本名称")private String bookname;
/*** 书本价格*/@ApiModelProperty(value="书本价格")private Double price;
/*** 书本类型*/@ApiModelProperty(value="书本类型")private String booktype;
private static final long serialVersionUID = 1L;
}
@ApiParam
作用在方法的参数上,用来描述接口的参数信息(一个参设置一个)
@ApiParam
必须与@RequestParam
、@PathVariable
和@RequestHeader
一起使用。
属性 | 说明 |
---|---|
name | 参数名称 |
value | 参数简单描述 |
defaultValue | 描述参数默认值 |
required | 是否为必传参数, false:非必传; true:必传 |
allowMultiple | 指定参数是否可以通过多次出现来接收多个值 |
hidden | 隐藏参数列表中的参数 |
example | 非请求体(body)类型的单个参数示例 |
examples | @Example(value = @ExampleProperty(mediaType = “”, value = “”)) 参数示例,仅适用于请求体类型的请求 |
案例演示
@ApiOperation(value="新增书本信息1",notes="新增书本信息1")
@PostMapping("/addBooks")
public JsonResponseBody<?> addBooks(@ApiParam(name="bookName",value="bookName",required = true) @RequestParam("bookName") String bookName,@ApiParam(name="price",value="price",required = true) @RequestParam("price") float price,@ApiParam(name="bookType",value="bookType",required = true) @RequestParam("bookType") String bookType){System.out.println("bookName="+bookName+",price="+price+",bookType="+bookType);return new JsonResponseBody<>();
}
生产环境下屏蔽Swagger2
为了保证接口文档的安全,禁用了生产环境的加载,具体说明请看:
参考地址:https://www.jianshu.com/p/fa3230ffb27c
一般生产环境是不能放开swagger的,这样接口暴露在外网很不安全!!!
一般生产环境是不能放开swagger的,这样接口暴露在外网很不安全!!!
一般生产环境是不能放开swagger的,这样接口暴露在外网很不安全!!!
修改Swagger2配置类
添加@Profile注解,指明在何种环境下可以使用Swagger2,一般情况下只有在开发(dev)和测试(test)环境下才可以使用Swagger2;而在生产(dev)环境下不能使用Swagger2。
@Configuration
//开启Swagger2
@EnableSwagger2
//配置生产环境下不可用 dev(开发)、test(测试)、prod(生产)
@Profile({"dev","test"})
public class Swagger2Configuration extends WebMvcConfigurationSupport {...@Overrideprotected void addResourceHandlers(ResourceHandlerRegistry registry) {registry.addResourceHandler("doc.html")
.addResourceLocations("classpath:/META-INF/resources/");registry.addResourceHandler("/webjars/**")
.addResourceLocations("classpath:/META-INF/resources/webjars/");}
}
修改application.yml
修改application.yml文件,配置项目系统的运行环境(dev/test/prod)
spring:#配置swagger2生产和测试环境不可用profiles:active: prod
使用maven package打包测试
运行测试
打开CMD,跳转到target目录,输入命令:java -jar .\xxx.jar --spring.profiles.active=prod。可以直接打开jar包修改application.yml配置文件中spring.profiles.active属性切换运行环境,具体请参考以下配置:
开发环境:dev;
生产环境:prod;
测试环境:test;
以上就是今天有关于Swagger2的介绍和使用!
第二章:Swagger2相关推荐
- 19年8月 字母哥 第二章 RESTFul接口实现与测试 看到这里了
第二章 RESTFul接口实现与测试 2.1.RESTFul接口与http协议状态表述 2.2.常用注解开发一个RESTFul接口 2.2看完了 2.3 JSON数据处理与PostMan测试 树哪 ...
- 19年8月 字母哥 第一章 spring boot 2.x基础及概念入门 这里全部看完了 热部署没出来 第二章在前面2页 用热点公司网不行
http://springboot.zimug.com/1233100 文档 http://www.zimug.com/page/5 字母哥个人博客 11111 第一章 spring bo ...
- 王道考研 计算机网络笔记 第二章:物理层
本文基于2019 王道考研 计算机网络: 2019 王道考研 计算机网络 个人笔记总结 第一章:王道考研 计算机网络笔记 第一章:概述&计算机网络体系结构 后续章节将陆续更新- 第二章 一.物 ...
- 计算机组成原理-第二章 数据表示与运算
计算机组成原理-第二章 数据表示与运算 一.数据的表示 1.数值型数据的表示(重点难点) 1.1数值型数据的表示--进位制 1.2数值型数据表示-码制 1.3数值型数据的表示--定点数 1.4数值型数 ...
- 2021-08-08概率论与数理统计-第二章
文章目录 概率论与数理统计-第二章 概率论与数理统计-第二章
- 软件构造 第二章 第一节 软件生命周期和版本控制
软件构造第二章 第一节 软件生命周期和版本控制 基本内容 Software Development Lifecycle (SDLC) Traditional software process mode ...
- 第二节认识计算机教案,第二章 第二节 局域网的构建 教学设计_博客
<第二章 第二节 局域网的构建 教学设计_博客>由会员分享,可在线阅读,更多相关<第二章 第二节 局域网的构建 教学设计_博客(3页珍藏版)>请在装配图网上搜索. 1.第二章 ...
- ArcGIS for Desktop入门教程_第二章_Desktop简介 - ArcGIS知乎-新一代ArcGIS问答社区
原文:ArcGIS for Desktop入门教程_第二章_Desktop简介 - ArcGIS知乎-新一代ArcGIS问答社区 1 Desktop简介 1.1 ArcGIS for Desktop ...
- 第二章 序列比对——Needleman-Wunsch全局比对
[生信]第二章 序列比对--Needleman-Wunsch全局比对 主要为基因组测序比对相关知识,部分内容作笔记自查使用.如有错误或遗漏还请海涵,可评论或邮箱联系. 最后修改时间:2020-04-0 ...
- 第二章 序列比对——Blast局部比对
第二章 序列比对--Blast局部比对 阅读量: 330 主要为基因组测序比对相关知识,部分内容作笔记自查使用.如有错误或遗漏还请海涵,可评论或邮箱联系. 最后修改时间:2020-04-16 16: ...
最新文章
- findclass java_Java Context.findClass方法代码示例
- pip无法更新_TensorFlow 2.0「开发者预览版」上线,内容每日更新
- RabbitMQ(二):mandatory标志的作用
- ABAP, UI5和webpack的处理入口
- python对比两张图片_用python实现对比两张图片的不同
- Java集合和泛型练习及面试题——博客园:师妹开讲啦
- 大数据学习(0)-大数据知识框图
- 使用Lucid Virtu在有独立显卡的情况下使用Intel硬件加速H.264编码
- QWT错误static struct QMetaObject const QwtPlot
- Unity Shader 记录
- [转]tar 命令使用
- Spring Boot官方文档笔记
- 5y计算机应用2010综合测评答案,计算机二级习题答案
- 洛谷 P4093 [HEOI2016/TJOI2016]序列(Cdq+dp)
- 计算机网络期中考试总结反思,期中考试总结反思600字
- 实战sqlmap绕过WAF(中转注入)
- 命名空间Microsoft.Office中不存在类型或命名空间名Core
- PMP之总价合同、成本补偿合同、工料合同
- @RunWith和@ContextConfiguration的用法
- 开源手游暗黑世界客户端部分代码注解续
热门文章
- CFA【异常检测:Embedding_based】
- 刚子扯谈:一起聊聊微信这孙子
- html div父集子集,怎么让父极元素的宽度自动设为所有子集的宽度之和呢?或者怎么保证子集不换行?不考虑用js!...
- oracle数据库字符集子集与超集对应关系表表
- Windows 搜索
- 高中计算机会考怎么考,会考通过需多少分
- 黑马程序员——Java基础——网络编程1
- Mysql5.5命令行修改密码
- java 框架GAT_GAT2.0使用文档(组合接口测试)
- 高数知识点整理——有理分式的不定积分(多项式的除法)