一、前言Swagger是一款可以快速生成符合RESTful风格API并进行在线调试的插件。本文将介绍如何在Spring Boot中整合Swagger。在此之前我们先聊聊什么是REST。REST实际上为Representational State Transfer的缩写翻译为“表现层状态转化” 。如果一个架构符合REST 原则就称它为RESTful架构。实际上“表现层状态转化”省略了主语完整的说应该是“资源表现层状态转化”。什么是资源Resource资源指的是网络中信息的表现形式比如一段文本一首歌一个视频文件等等什么是表现层Reresentational表现层即资源的展现在你面前的形式比如文本可以是JSON格式的也可以是XML形式的甚至为二进制形式的。图片可以是gif也可以是PNG什么是状态转换State Transfer用户可使用URL通过HTTP协议来获取各种资源HTTP协议包含了一些操作资源的方法比如GET 用来获取资源 POST 用来新建资源 , PUT 用来更新资源 DELETE 用来删除资源 PATCH 用来更新资源的部分属性。通过这些HTTP协议的方法来操作资源的过程即为状态转换。下面对比下传统URL请求和RESTful风格请求的区别描述传统请求方法RESTful请求方法查询/user/query?namemrbirdGET/user?namemrbirdGET详情/user/getInfo?id1GET/user/1GET创建/user/create?namemrbirdPOST/userPOST修改/user/update?namemrbirdid1POST/user/1PUT删除/user/delete?id1GET/user/1DELETE从上面这张表我们大致可以总结下传统请求和RESTful请求的几个区别传统请求通过URL来描述行为如createdelete等RESTful请求通过URL来描述资源。RESTful请求通过HTTP请求的方法来描述行为比如DELETEPOSTPUT等并且使用HTTP状态码来表示不同的结果。RESTful请求通过JSON来交换数据。注意:RESTful只是一种风格并不是一种强制性的标准。二、引入Swagger依赖本文使用的Swagger版本为2.9.2dependencygroupIdio.springfox/groupIdartifactIdspringfox-swagger2/artifactIdversion2.9.2/version/dependencydependencygroupIdio.springfox/groupIdartifactIdspringfox-swagger-ui/artifactIdversion2.9.2/version/dependency三、配置SwaggerConfig使用JavaConfig的形式配置SwaggerConfigurationEnableSwagger2publicclassSwagger2Config{//api接口包扫描路径publicstaticfinalStringSWAGGER_SCAN_BASE_PACKAGEcom.wno704.boot.controller;publicstaticfinalStringVERSION1.0.0;BeanpublicDocketcreateRestApi(){returnnewDocket(DocumentationType.SWAGGER_2).apiInfo(apiInfo()).select().apis(RequestHandlerSelectors.basePackage(SWAGGER_SCAN_BASE_PACKAGE))//.apis(RequestHandlerSelectors.withMethodAnnotation(ApiOperation.class)).paths(PathSelectors.any())// 可以根据url路径设置哪些请求加入文档忽略哪些请求.build();}privateApiInfoapiInfo(){returnnewApiInfoBuilder().title(系统RESTful API文档)//设置文档的标题.description(系统RESTful API文档)// 设置文档的描述.version(VERSION)// 设置文档的版本信息- 1.0.0 Version information.termsOfServiceUrl(http://www.wno704.com)// 设置文档的License信息-1.3 License information.contact(newContact(wno704,http://www.wno704.com,wno704126.com)).build();}}在配置类中添加EnableSwagger2注解来启用Swagger2apis()定义了扫描的包路径。配置较为简单其他不做过多说明。四、Swagger常用注解Api修饰整个类描述Controller的作用ApiOperation描述一个类的一个方法或者说一个接口ApiParam单个参数描述ApiModel用对象来接收参数ApiProperty用对象接收参数时描述对象的一个字段ApiResponseHTTP响应其中1个描述ApiResponsesHTTP响应整体描述ApiIgnore使用该注解忽略这个APIApiError 发生错误返回的信息ApiImplicitParam一个请求参数ApiImplicitParams多个请求参数。五、编写RESTful API接口Spring Boot中包含了一些注解对应于HTTP协议中的方法GetMapping对应HTTP中的GET方法PostMapping对应HTTP中的POST方法PutMapping对应HTTP中的PUT方法DeleteMapping对应HTTP中的DELETE方法PatchMapping对应HTTP中的PATCH方法。我们使用这些注解来编写一个RESTful测试ControllerApi(value用户Controller)RestControllerRequestMapping(user)publicclassUserController{ApiIgnoreGetMapping(hello)publicResponseBodyStringhello(){returnhello;}ApiOperation(value获取用户信息,notes根据用户id获取用户信息,producesapplication/json)ApiImplicitParam(nameid,value用户id,requiredtrue,dataTypeInteger,paramTypepath)GetMapping(/{id})publicResponseBodyUsergetUserById(PathVariable(valueid)Longid){UserusernewUser();user.setId(id);user.setName(mrbird);user.setAge(25);returnuser;}ApiOperation(value获取用户列表,notes获取用户列表)GetMapping(/list)publicResponseBodyListUsergetUserList(){ListUserlistnewArrayList();Useruser1newUser();//user1.setId(1l);user1.setName(mrbird);user1.setAge(25);list.add(user1);Useruser2newUser();//user2.setId(2l);user2.setName(scott);user2.setAge(29);list.add(user2);returnlist;}ApiOperation(value新增用户,notes根据用户实体创建用户)ApiImplicitParam(nameuser,value用户实体,requiredtrue,dataTypeUser,paramTypequery)PostMapping(/add)publicResponseBodyMapString,ObjectaddUser(RequestBodyUseruser){MapString,ObjectmapnewHashMap();map.put(result,success);returnmap;}ApiOperation(value删除用户,notes根据用户id删除用户)ApiImplicitParam(nameid,value用户id,requiredtrue,dataTypeInteger,paramTypepath)DeleteMapping(/{id})publicResponseBodyMapString,ObjectdeleteUser(PathVariable(valueid)Longid){MapString,ObjectmapnewHashMap();map.put(result,success);returnmap;}ApiOperation(value更新用户,notes根据用户id更新用户)ApiImplicitParams({ApiImplicitParam(nameid,value用户id,requiredtrue,dataTypeInteger,paramTypepath),ApiImplicitParam(nameuser,value用户实体,requiredtrue,dataTypeUser,paramTypequery)})PutMapping(/{id})publicResponseBodyMapString,ObjectupdateUser(PathVariable(valueid)Longid,RequestBodyUseruser){MapString,ObjectmapnewHashMap();map.put(result,success);returnmap;}}使用的实体类UserGetterSetterpublicclassUserimplementsSerializable{privatestaticfinallongserialVersionUID-2731598327208972274L;privateLongid;privateStringname;privateIntegerage;}对于不需要生成API的方法或者类只需要在上面添加ApiIgnore注解即可。六、启动测试启动项目访问http://localhost:8080/swagger-ui.html即可看到Swagger给我们生成的API页面