接口文档生成工具Swagger2的使用

一、什么是Swagger

Swagger 是一个规范和完整的框架,用于生成、描述、调用和可视化 RESTful 风格的 Web 服务。总体目标是使客户端和文件系统作为服务器以同样的速度来更新。文件的方法,参数和模型紧密集成到服务器端的代码,允许API来始终保持同步。

作用

1. 接口的文档在线自动生成。

2. 功能测试。

二、个人感受

​ 我之前一直是项目运行调试,但是发现这样效率太低,又用了Postman来调试。Postman是谷歌的一个网页调试工具,非常适合JavaWeb调试。但是现在我要介绍另一个更不错的,那就是Swagger工具,这里我是用SpringBoot框架来做的。比较简单的,可以用来学习Swagger来测试前端和后端的运行。就像下面这个图片,Swagger就是中间Restful接口的一种测试框架,可以单元测试前后端的运行状态,提高开发效率。

img

二、在Maven中添加依赖

版本Swagger太高出现问题,

i.s.m.p.AbstractSerializableParameter : Illegal DefaultValue null for parameter type integer
java.lang.NumberFormatException: For input string: “”at io.swagger.models.parameters.AbstractSerializableParameter.getExample(AbstractSerializableParameter.java:412) ~[swagger-models-1.5.20.jar:1.5.20]原因:
if (BaseIntegerProperty.TYPE.equals(type)) {return Long.valueOf(example);
}//实体属性类型是Integer,就把example转为Long类型,而example默认为"",导致转换错误。

所以需要降低版本 swagger-models

<!-- https://mvnrepository.com/artifact/io.springfox/springfox-swagger-ui --><dependency><groupId>io.springfox</groupId><artifactId>springfox-swagger-ui</artifactId><version>2.9.2</version></dependency><dependency><groupId>io.springfox</groupId><artifactId>springfox-swagger2</artifactId><version>2.9.2</version><exclusions><exclusion><groupId>io.swagger</groupId><artifactId>swagger-models</artifactId></exclusion></exclusions></dependency><dependency><groupId>io.swagger</groupId><artifactId>swagger-models</artifactId><version>1.5.21</version></dependency>

三、创建Swagger2的配置类

/*** Swagger2 配置类* 在与spring boot 集成时,放在与application.java 同级的目录下* 通过@Configuration注解,让spring来加载该配置* 再通过@EnableSwagger2注解来启动Swagger2*/
@Configuration
@EnableSwagger2
public class Swagger2 {/*** 创建API应用* appinfo()增加API相关信息* 通过select()函数返回一个ApiSelectorBuilder实例,用来控制那些接口暴露给Swagger来展现* 本例采用置顶扫描的包路径来定义指定要建立API的目录** @return*/@Beanpublic Docket createRestApi(){Docket docket = new Docket(DocumentationType.SWAGGER_2).apiInfo(apiInfo()).select().apis(RequestHandlerSelectors.basePackage("com.xzp.springboot.springboot.controller")).paths(PathSelectors.any()).build();return docket;}/*** 创建改API的基本信息(这些基本信息会展示在文档页面中)* 访问地址: http://项目实际地址/swagger-ui.html* @return*/private ApiInfo apiInfo(){return new ApiInfoBuilder().title("swagger-api文档").description("swagger文档 by 13").termsOfServiceUrl("http://www.baidu.com").version("1.0").build();}
}

四 创建Controller的控制类

public class User implements Serializable {private Integer id;private String name;private String password;public Integer getId() {return id;}public void setId(Integer id) {this.id = id;}public String getName() {return name;}public void setName(String name) {this.name = name;}public String getPassword() {return password;}public void setPassword(String password) {this.password = password;}
}
@RestController
public class TestSwaggerController {static Map<Integer, User> usersMap = Collections.synchronizedMap(new HashMap<Integer, User>());// 初始化 usersMapstatic {User user = new User();user.setId(1);user.setName("lou1");user.setPassword("111111");User user2 = new User();user2.setId(2);user2.setName("lou2");user2.setPassword("222222");usersMap.put(1, user);usersMap.put(2, user2);}@ApiOperation(value = "获取用户列表" , notes = "查看")@GetMapping(value = "/users")public List<User> getUserList(){List<User> users = new ArrayList<>(usersMap.values());return users;}@ApiOperation(value = "新增加用户" , notes = "根据User对象新增加用户")@ApiImplicitParam(name = "user" , value = "用户实体" , required = true , dataType = "User")@PostMapping("/insert")public String postUser(@RequestBody User user){usersMap.put(user.getId(),user);return "新增加成功!";}@ApiOperation(value = "获取用户详细信息" , notes = "根据id来获取用户详细信息")@ApiImplicitParam(name = "id" , value = "用户id" , required = true , dataType = "int")@GetMapping(value = "/getOne/{id}")public User getUser(@PathVariable Integer id){return usersMap.get(id);}@ApiOperation(value = "更新用户详细信息", notes = "")@ApiImplicitParams({@ApiImplicitParam(name = "id", value = "用户id", required = true, dataType = "int"),@ApiImplicitParam(name = "user", value = "用户实体user", required = true, dataType = "User")})@PutMapping("/users/{id}")public String putUser(@PathVariable Integer id, @RequestBody User user) {User tempUser = usersMap.get(id);tempUser.setName(user.getName());tempUser.setPassword(user.getPassword());usersMap.put(id, tempUser);return "更新成功";}@ApiOperation(value = "删除用户", notes = "根据id删除对象")@ApiImplicitParam(name = "id", value = "用户id", required = true, dataType = "int")@DeleteMapping("/users/{id}")public String deleteUser(@PathVariable Integer id) {usersMap.remove(id);return "删除成功";}}

成功:

img

四、Swagger2 的注解使用

  • @Api:用在类上,说明该类的作用。
  • @ApiOperation:注解来给API增加方法说明。
  • @ApiImplicitParams : 用在方法上包含一组参数说明。
  • @ApiImplicitParam:用来注解来给方法入参增加说明。
  • @ApiResponses:用于表示一组响应
  • @ApiResponse:用在@ApiResponses中,一般用于表达一个错误的响应信息
  • * code:数字,例如400
  • * message:信息,例如"请求参数没填好"
  • * response:抛出异常的类
  • @ApiModel:描述一个Model的信息(一般用在请求参数无法使用@ApiImplicitParam注解进行描述的时候)
  • * @ApiModelProperty:描述一个model的属性

注意:@ApiImplicitParam的参数说明:

paramType:指定参数放在哪个地方header:请求参数放置于Request Header,使用@RequestHeader获取query:请求参数放置于请求地址,使用@RequestParam获取path:(用于restful接口)–>请求参数的获取:@PathVariablebody:(不常用)form(不常用)
name:参数名
dataType:参数类型
required:参数是否必须传true | false
value:说明参数的意思
defaultValue:参数的默认值

关于文件上传的Swagger2:

@Api("ChatInfoController|图片和音频上传控制器类")
@RestController
public class ChatInfoController {/*** 上传图片接口* @param attach 文件对象* @param request http请求* @return imgSrc:上传后图片文件的路径*/@ApiOperation(value = "上传图片",notes = "文件不能超过20M大小,后缀名为png,jpg,gif")@RequestMapping(value = "/uploadImg",method = RequestMethod.POST)@ResponseBodypublic String uploadImg(@RequestParam("file") MultipartFile attach,HttpServletRequest request) {System.out.println("上传图片");return FileUp.upFile(attach, request, Constants.IMAGE, true);}/*** 上传语音接口* @param attach 文件对象* @param request http请求* @return audioSrc:上传后语音文件的路径*/@ApiOperation(value = "上传语音",notes = "文件不能超过20M大小,后缀名为MP3,silk,flv")@RequestMapping(value = "/uploadAudio",method = RequestMethod.POST)@ResponseBodypublic String uploadAudio( @RequestParam("file") MultipartFile attach,HttpServletRequest request) {System.out.println("上传语音");return FileUp.upFile(attach, request, Constants.AUDIO, true);}}

添加注解后启动springboot,输入http://localhost:8080/swagger-ui.html即可进入文档页面

img

本文来自互联网用户投稿,该文观点仅代表作者本人,不代表本站立场。本站仅提供信息存储空间服务,不拥有所有权,不承担相关法律责任。如若转载,请注明出处:http://www.mzph.cn/news/557084.shtml

如若内容造成侵权/违法违规/事实不符,请联系多彩编程网进行投诉反馈email:809451989@qq.com,一经查实,立即删除!

相关文章

Netty详解

一&#xff0e;Netty介绍 1.什么是netty Netty 是由 JBOSS 提供的一个 Java 开源框架。Netty 提供异步的、基于事件驱动的网络应用程序框架&#xff0c;用以快速开发高性能、高可靠性的网络 IO 程序,是目前最流行的 NIO 框架&#xff0c;Netty 在互联网领域、大数据分布式计算…

有没有检查c语言编译错误的软件,求大佬解答,为什么这个程序编译软件检查不出错误...

该楼层疑似违规已被系统折叠 隐藏此楼查看此楼#include#include /* malloc()等 */#include#include#include /* exit() */#define TRUE 1#define FALSE 0#define OK 1#define ERROR 0#define OVERFLOW -2typedef int Status; /* Status是函数的类型,其值是函数结果状态代码&…

语法分析器c语言实验报告,词法分析实验报告(C++)..doc

词法分析实验报告(C).词法分析实验报告一、实验目的1. 掌握词法分析的原理。2. 熟悉保留字表等相关的数据结构与单词的分类方法。3. 掌握词法分析器的设计与调试。二、实验内容根据编译中的分词原理,用C语言编写一个C语言的词法分析程序:.三、实验要求1. 输入:任意一个C语言程序…

详解 Java NIO

详解 Java NIO 文件的抽象化表示&#xff0c;字节流以及字符流的文件操作等属于传统 IO 的相关内容&#xff0c;我们已经在前面的文章进行了较为深刻的学习了。 但是传统的 IO 流还是有很多缺陷的&#xff0c;尤其它的阻塞性加上磁盘读写本来就慢&#xff0c;会导致 CPU 使用…

转专业计算机c语言,转专业申请美国计算机专业研究生必须要做的准备

先修课——转专业申计算机时&#xff0c;补先修课是使自己match的重要的一步。1.纽约大学的计算机硕士项目(计算机系的M.S. in Computer Science和M.S. in Information Systems项目)对申请人的先修课要求&#xff1a;The minimum prerequisite background for admission to the…

使用between and查找时间范围时的日期边界问题

最近在一个项目的后台数据库查找中&#xff0c;需要根据表中的时间字段查找某一范围内的数据&#xff08;7天、15天、30天&#xff09;&#xff0c;这时我想用between and&#xff08;其实使用DateDiff函数就可以完成&#xff0c;详情请看另一片文章&#xff1a;SQL查询今天、昨…

c语言画爱心附带解释,用C语言画一个“爱心”

/*每个main函数代表一种形状*/#includeusing namespacestd;#include#include/*int main(void){for(float y 1.5f;y > -1.5f;y - 0.06f){for(float x -1.5f;x < 1.5f;x 0.03f){float a x * x y * y - 1;putchar(a * a * a - x * x * y * y * y < 0.0f?^: );}putc…

SQL查询今天、昨天、7天内、30天

今天的所有数据&#xff1a;select * from 表名 where DateDiff(dd,datetime类型字段,getdate())0 昨天的所有数据&#xff1a;select * from 表名 where DateDiff(dd,datetime类型字段,getdate())1 7天内的所有数据&#xff1a;select * from 表名 where DateDiff(dd,dateti…

C语言入门I love China,C语言从入门到精通

如何学习C语言 Ⅰ第1篇 基础知识开启C语言编程世界之门。第1章 步入C的世界——Hello C 2视频教学录像&#xff1a;1小时34分钟你可能已经听说或知道一点C语言&#xff0c;也可能没有任何基础&#xff0c;没关系&#xff0c;本章就带领你进入C语言的编程世界。1.1 了解C语…

电气工程及其自动化学不学c语言,电气工程及其自动化学什么 就业方向有哪些...

电气工程及其自动化学什么 就业方向有哪些2019-05-05 11:16:29文/刘美娟电气工程及其自动化专业是电气信息领域的一门新兴学科&#xff0c;触角伸向各行各业&#xff0c;小到一个开关的设计&#xff0c;大到宇航飞机的研究&#xff0c;都有它的身影。由于和人们的日常生活以及工…

Tomcat(一):简介

一、概念 Tomcat 服务器是一个开源的轻量级Web应用服务器&#xff0c;在中小型系统和并发量小的场合下被普遍使用&#xff0c;是开发和调试Servlet、JSP 程序的首选。 二、原理 Tomcat结构图&#xff1a; ​ Tomcat主要组件&#xff1a;服务器Server&#xff0c;服务Serv…

Tomcat(二):server.xml配置

一、server.xml详解 Tomcat各组件关系图 ​ 1、Server ​ server.xml的最外层元素。 常用属性&#xff1a; ​ port&#xff1a;Tomcat监听shutdown命令的端口。 ​ shutdown&#xff1a;通过指定的端口&#xff08;port&#xff09;关闭Tomcat所需的字符串。修改shutd…

c语言的表达式2 4 6 8的值,C语言程序设计测试题二

一、判断题(每题2分&#xff0c;共8分)1.若有int ⅰ10, j0; 则执行完语句if (j0)ⅰ ; else ⅰ- -;ⅰ的值为11。()2.若有 int ⅰ5, j10; 则执行完语句switch ( i ){case 4: j ;case 5: j- - ;case 6: j ;case 7: j- 2;default: ;}后j的值为8。 ( )3.若有 int i10, j2;则执行完ⅰ…

Tomcat(三):日志

一、Tomcat 日志概述 日志分为两种&#xff0c;系统日志和控制台日志。 系统日志主要包含运行中日志和访问日志&#xff0c;分为5类&#xff1a;catalina、localhost、manager、localhost_access、host-manager。在logging.properties文件中进行配置。 控制台日志包含了cata…

Tomcat(四):发布和优化

一、发布Web项目的三种方式 1、在server.xml文件中找到标签元素&#xff0c;在其下使用标签配置&#xff0c;一个标签就代表一个web应用。 path属性&#xff1a;虚拟目录的名称&#xff0c;也就是对外访问路径。 docBase属性&#xff1a;web应用所在硬盘中目录地址 reloada…

c语言中foreach的用法,详解JavaScript中的forEach()方法的使用

JavaScript数组的 forEach()方法调用数组中的每个元素。语法array.forEach(callback[, thisObject]);下面是参数的详细信息&#xff1a;callback : 函数测试数组的每个元素。thisObject : 对象作为该执行回调时使用。返回值:返回创建数组。兼容性&#xff1a;这种方法是一个Jav…

Java保留两位小数的几种写法总结

相信大家在平时做项目时&#xff0c;可能会有这样的业务需求&#xff1a; 页面或界面上展示的数据保留小数点后两位。 那么这篇文章小编就和大家分享了利用Java保留两位小数的几种写法&#xff0c;文章给出了详细的示例代码&#xff0c;对大家的学习和理解很有帮助&#xff0c;…

二级c语言基础题库100题,二级C语言上题库100题.doc

二级C语言上题库100题二级C语言上机试题汇编第01套&#xff1a;给定程序中&#xff0c;函数fun的功能是&#xff1a;将形参n所指变量中&#xff0c;各位上为偶数的数去除,剩余的数按原来从高位到低位的顺序组成一个新的数&#xff0c;并通过形参指针n传回所指变量。例如&#x…

spring boot + vue 前后端分离时间戳转换为 yyyy:MM:dd HH:mm:ss格式

后端 1.model(entity)注释直接转换 当返回类型为resultMap&#xff0c;在entity类里面相应属性上加上以下注释 JsonFormat(pattern“yyyy-MM-dd HH:mm:ss”,timezone“GMT8”)2.Mapper.xml里sql语句转换 select DATE_FORMAT(对应时间属性,’’%Y-%m-%d %H:%i:%s’’) from …

android:configchanges的作用,将uiMode附加到android:configChanges实际做什么?

我只是修复了我们应用程序中的错误.问题在于,对接或取消对接设备会导致应用程序重新启动.我在拖曳大量论坛线程后发现了此修复程序,是将uiMode附加到AndroidManifest.xml文件中的android&#xff1a;configChanges属性&#xff1a;我想确保通过提交此更改,我不会破坏其他重要功…