SpringBoot中使用Swagger

1.简介

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

Swagger消除了在调用服务过程可能有的猜测。

2.使用

前提是使用Maven的SpringBoot的web项目

(1)在pom文件里面添加如下依赖:

1
2
3
4
5
6
7
8
9
10
<dependency><!-- -->
<groupId>io.springfox</groupId>
<artifactId>springfox-swagger2</artifactId>
<version>2.2.2</version>
</dependency>
<dependency><!-- 用于生成比较直观的APIs -->
<groupId>io.springfox</groupId>
<artifactId>springfox-swagger-ui</artifactId>
<version>2.2.2</version>
</dependency>

(2)在我们项目启动类的同级目录下新建一个Swagger2的配置类。

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
@Configuration
@EnableSwagger2
public class Swagger2 {
/**
* 创建API应用
* apiInfo() 增加API相关信息
* 通过select()函数返回一个ApiSelectorBuilder实例,用来控制哪些接口暴露给Swagger来展现,
* 本例采用扫描任意的文件,如果需要自定义需要扫描的文件,可以 :.apis(RequestHandlerSelectors.basePackage("com.swaggerTest.controller"))
*
* @return
*/
@Bean
public Docket createRestApi() {
return new Docket(DocumentationType.SWAGGER_2)
.apiInfo()
.select()
.apis(RequestHandlerSelectors.any())
.paths(PathSelectors.any())
.build();
}
//对于这个APIs的一个介绍和一些相关的基础信息的描述
//访问地址:http://项目实际地址/swagger-ui.html
private ApiInfo apiInfo() {
return new ApiInfoBuilder()
.title("Spring Boot中使用Swagger2构建RESTful APIs")
.description("更多Spring Boot相关文章请关注:http://happywayq.com/")
.termsOfServiceUrl("http://happywayq.com/")
.contact("叫我DaMiss")
.version("1.0")
.build();
}
}

如上代码所示,通过createRestApi函数创建Docket的Bean之后,apiInfo()用来创建该Api的基本信息(这些基本信息会展现在文档页面中)。

(3)写一个REST风格的controller

1
2
3
4
5
6
7
8
@RestController
public class FirstController {
@ApiOperation(value="开始测试home方法", notes="")
@RequestMapping(value="/hello/{name}",method=RequestMethod.GET)//注意要写上请求方法的类型,不然在生成APIs的时候会显示所有的请求方法的文档。
public String home(@PathVariable String name) {
return "Hello:"+name;
}
}

(4)启动我们的项目

在地址栏输入URL:http://localhost:8080/swagger-ui.html 就可以看到我们的API。

【注意】这个URL是从我们的项目的根路径开始的,如果你的不是可以自行修改 ,例如:http://localhost:8080/xxx/swagger-ui.html 。点开一个方法还可以进行测试。

(5)添加文档内容

在完成了上述配置后,其实已经可以生产文档内容,但是这样的文档主要针对请求本身,描述的主要来源是函数的命名,对用户并不友好,我们通常需要自己增加一些说明来丰富文档内容。

Swagger 的注解说明

@Api:用在类上,说明该的作用。

1
2
3
4
5
@RestController
@Api(value="FirstController|一个用来测试Swagger的控制器")
public class FirstController {
//......
}

@ApiOperation:注解来给API增加方法说明。

1
2
3
4
5
6
@ApiOperation(value="开始测试home方法", notes="传入的参数是人名")
//@RequestMapping要写上请求方法的类型否则SawggerUi会默认为全类型皆可访问, API列表中会生成多条项目。
@RequestMapping(value="/hello/{name}",method=RequestMethod.GET)
public String home(@PathVariable String name) {
return "Hello:"+name;
}

@ApiImplicitParams : 用在方法上包含一组参数说明。

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
@RequestMapping("/updatePassword")
@ApiOperation(value="修改用户密码", notes="根据用户id修改密码")
@ApiImplicitParams({
@ApiImplicitParam(paramType="query", name = "userId", value = "用户ID", required = true, dataType = "Integer"),
@ApiImplicitParam(paramType="query", name = "password", value = "旧密码", required = true, dataType = "String"),
@ApiImplicitParam(paramType="query", name = "newPassword", value = "新密码", required = true, dataType = "String")
})
public String updatePassword(@RequestParam(value="userId") Integer userId, @RequestParam(value="password") String password,
@RequestParam(value="newPassword") String newPassword){
if(userId <= 0 || userId > 2){
return "未知的用户";
}
if(StringUtils.isEmpty(password) || StringUtils.isEmpty(newPassword)){
return "密码不能为空";
}
if(password.equals(newPassword)){
return "新旧密码不能相同";
}
return "密码修改成功!";
}

@ApiImplicitParam:用来注解来给方法入参增加说明。

1
2
3
4
5
6
7
8
9
10
11
12
13
14
@RequestMapping(value ="/getUserName", method= RequestMethod.GET)
@ApiOperation(value="根据用户编号获取用户姓名", notes="test: 仅1和2有正确返回")
@ApiImplicitParam(paramType="query", name = "userNumber", value = "用户编号", required = true, dataType = "Integer")
public String getUserName(@RequestParam Integer userNumber){
if(userNumber == 1){
return "张三丰";
}
else if(userNumber == 2){
return "慕容复";
}
else{
return "未知";
}
}

@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:参数的默认值

项目源码:https://github.com/happyfyq/springBootSwagger

坚持原创技术分享,您的支持将鼓励我继续创作!

分享
Fork me on GitHub