Swagger是什么？
Swagger是一个规范和完整的框架，用于生成、描述、调用和可视化 RESTful风格的Web服务。总体目标是使客户端和文件系统作为服务器以同样的速度来更新。文件的方法，参数和模型紧密集成到服务器端的代码，允许API来始终保持同步。
Swagger的作用主要有以下两点：
- 接口的文档在线自动生成。
- 功能测试。
在SpringBoot中使用Swagger2生成接口文档
1.引入Swagger2相关依赖。
<dependency>
<groupId>io.springfox</groupId>
<artifactId>springfox-swagger2</artifactId>
<version>2.2.2</version>
</dependency>
<dependency>
<groupId>io.springfox</groupId>
<artifactId>springfox-swagger-ui</artifactId>
<version>2.2.2</version>
</dependency>
2.在Application.java的同级包路径下创建Swagger2的配置类Swagger2。
package com.wunian.swagger;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import springfox.documentation.builders.ApiInfoBuilder;
import springfox.documentation.builders.PathSelectors;
import springfox.documentation.builders.RequestHandlerSelectors;
import springfox.documentation.service.ApiInfo;
import springfox.documentation.spi.DocumentationType;
import springfox.documentation.spring.web.plugins.Docket;
import springfox.documentation.swagger2.annotations.EnableSwagger2;
/**
* @author wunian
* @desc Swagger配置类
*
* @createdate 2019/9/27
*/
@Configuration //让spring来加载该类配置
@EnableSwagger2 //启用Swagger2
public class Swagger2 {
/**
* 创建API应用
* createApiInfo() 增加api相关信息
* 通过select()函数返回一个ApiSelectorBuilder实例，用来控制哪些接口暴露给Swagger来展现
* 采用指定扫描的包路径来定义指定要建立API的目录
* @return
*/
@Bean
public Docket createRestApi(){
return new Docket(DocumentationType.SWAGGER_2)
.apiInfo(createApiInfo())
.select()
//暴露给Swagger的包路径
.apis(RequestHandlerSelectors.basePackage("com.wunian.swagger.controller"))
.paths(PathSelectors.any())
.build();
}
/**
* 创建该API的基本信息
* 访问地址：http://localhost:8080/swagger-demo/swagger-ui.html
* @return
*/
protected ApiInfo createApiInfo(){
return new ApiInfoBuilder()
//标题
.title("使用Swagger2来构建SpringBoot Restful APIs")
//标题下方的小字
.description("详情请关注https://swagger.io/resources/open-api/")
//组织服务地址
.termsOfServiceUrl("https://swagger.io/resources/open-api/")
//开发者
.contact("勿念")
//API版本
.version("0.1")
.build();
}
}
3.创建HelloController，添加Api方法并使用Swagger注解来对文档内容进行相关说明。
package com.wunian.swagger.controller;
import io.swagger.annotations.Api;
import io.swagger.annotations.ApiImplicitParam;
import io.swagger.annotations.ApiImplicitParams;
import io.swagger.annotations.ApiOperation;
import org.springframework.stereotype.Controller;
import org.springframework.util.StringUtils;
import org.springframework.web.bind.annotation.RequestMapping;
import org.springframework.web.bind.annotation.RequestMethod;
import org.springframework.web.bind.annotation.RequestParam;
import org.springframework.web.bind.annotation.ResponseBody;
/**
* @author wunian
* @desc 测试Swagger注解的控制器
* @createdate 2019/9/27
*/
@Controller
@RequestMapping("/hello")
//用在类上，说明该类的作用
@Api(value = "HelloController|一个用来测试swagger注解的控制器")
public class HelloController {
@ResponseBody
@RequestMapping(value = "/getUserName",method= RequestMethod.GET)
//给方法增加说明，notes是补充的说明
@ApiOperation(value = "根据用户ID获取用户姓名",notes = "userId:1为超级管理员，其他为普通用户")
//给方法入参增加说明，name：参数名，value：说明参数的意思，dataType：参数类型，required：参数是否必须传
//paramType：指定参数放在哪个地方，
//header：请求参数放置于Request Header，使用@RequestHeader获取
//query：请求参数放置于请求地址，使用@RequestParam获取
//path：（用于restful接口）-->请求参数的获取：@PathVariable
//body：（不常用）
//form（不常用）
@ApiImplicitParam(paramType = "query",name = "userId",value = "用户ID",dataType = "int")
public String getUserName(@RequestParam Integer userId){
if(userId==1){
return "Admin";
}else{
return "普通用户";
}
}
@ResponseBody
//Conntroller中定义的方法必须在@RequestMapper中显示的指定RequestMethod类型，
// 否则SawggerUi会默认为全类型皆可访问， API列表中会生成多条项目。
@RequestMapping("/updatePassword")
@ApiOperation(value = "修改用户密码",notes = "根据用户ID修改密码")
//用在方法上包含一组参数说明
@ApiImplicitParams({
//如果paramType与方法参数获取使用的注解不一致，会直接影响到参数的接收。
@ApiImplicitParam(paramType = "query",name = "userId",value = "用户ID",required = true,dataType = "int"),
@ApiImplicitParam(paramType = "query",name = "pwd",value = "旧密码",required = true,dataType = "String"),
@ApiImplicitParam(paramType = "query",name = "newPwd",value = "新密码",required = true,dataType = "String")
})
public String updatePassword(@RequestParam(value = "userId")Integer userId,
@RequestParam(value = "pwd")String pwd,
@RequestParam(value = "newPwd")String newPwd){
if(userId<0){
return "该用户不存在";
}
if(StringUtils.isEmpty(pwd)||StringUtils.isEmpty(newPwd)){
return "密码不能为空";
}
if(pwd.equals(newPwd)){
return "新密码不能和旧密码相同";
}
return "密码修改成功";
}
}
4.在application.properties文件中配置一些基本参数。
#服务端口
server.port=8081
#服务访问的上下文路径
server.servlet.context-path=/
#swagger.json的访问request mapping路径
springfox.documentation.swagger.v2.path=/api-docs
5.启动程序，在浏览器中访问http://localhost:8081/swagger-ui.html，出现如下界面说明接口文档生成成功。
swagger接口文档
6.点击方法列表可以看到该方法的详细信息和进行功能调试。
详细信息
功能测试
网友评论