您的位置:首页 > 编程语言 > Java开发

SpringBoot整合Swagger2实例方法

2019-06-20 14:32 911 查看

在进行软件开发的时候免不了要写接口文档,这些文档需要明确写出接口的类型、请求的URL、传参和返回值格式等信息,用于和前端交互或者提供给测试进行接口测试。但是手写文档一方面带给我们很大的工作量,另一方面如果接口有变更则需要频繁修改并且发给相关的人,无形中增加了工作量。小编为大家介绍一个生成文档的工具Swagger,上手简单,学习成本低,非常适合开发SpringBoot项目,现在就跟着小编一起学习吧。

首先需要在pom文件中加入swagger2的依赖,依赖的jar包如下图所示。

<dependency>
<groupId>io.springfox</groupId>
<artifactId>springfox-swagger2</artifactId>
<version>2.8.0</version>
</dependency>
<dependency>
<groupId>io.springfox</groupId>
<artifactId>springfox-swagger-ui</artifactId>
<version>2.8.0</version>
</dependency>

编写Swagger配置类Swagger2Config,在类上增加@Configuration和@EnableSwagger2注解,表明这是一个配置类,同时开启Swagger。如下的信息可以根据具体情况修改。

@Bean
public Docket api() {
return new Docket(DocumentationType.SWAGGER_2)
.apiInfo(apiInfo())
.select()
// 自行修改为自己的包路径
.apis(RequestHandlerSelectors.basePackage("com.spring.jpa.user"))
.paths(PathSelectors.any())
.build();
}

private ApiInfo apiInfo() {
return new ApiInfoBuilder()
.title("swagger-api文档")
.description("用户信息相关")
//服务条款网址
.termsOfServiceUrl("https://baidu.com")
.version("1.0")
.contact(new Contact("NWSL", "http://baidu.com", "111111@qq.com"))
.build();
}

 

接下来我们需要在Controller层添加注解,@Api(value="/test1", tags="测试用户接口模块"), @Api这个注解是用在请求的类上,表示对类的说明,其中tags="说明该类的作用,可以在UI界面上看到的注解",value="该参数没什么意义,在UI界面上也看到,所以不需要配置"。该注解的使用如下图所示。

 

接下来我们需要在方法上添加注解了,如下所示,@ApiOperation、@ApiImplicitParams、@ApiImplicitParam的作用如下图所示。@ApiResponses:用在请求的方法上,表示一组响@ApiResponse:用在@ApiResponses中,一般用于表达一个错误的响应信息。

在方法中的使用如下图所示。

@ApiOperation(value="添加用户信息", notes = "添加用户信息")
@ApiImplicitParams({
@ApiImplicitParam(name = "name", value = "用户姓名", required = true, dataType = "String",paramType = "query"),
@ApiImplicitParam(name = "age", value = "用户年龄", required = true,paramType = "query")
})

注意如果是Integer类型,那dataType = "Integer"就可以省略了,写上了反而在生成的文档调用的时候出错。

接下来我们介绍传实体类参数的注解怎么写,要使用到@ApiModel、@ApiModelProperty,具体的用法如下图所示。在接收参数的实体类上我们需要添加这两个注解,如下图所示。

接口上注解写完之后,我们启动服务,然后打开swagger的UI页面,注意8091端口是我本机服务启动的端口,请求的地址如下图所示。我们可以看到每个Controller类都生成了文档,UserController我们增加了类的注释。

接下来我们测试UserController中的接口,如下图所示,生成了UserController所有的接口文档,我们首先来看添加用户接口,如下图所示,为什么Integer类型的age字段,在生成的接口文档中参数类型变成了ref呢?上文提到过的,在写注解的时候,dataType = "Integer"要省略掉,不然会出现这个问题。正确的如下所示,可以看到age为Integer类型了。

我们可以看到在接口的右侧有Try it out,点击该按钮进入到调用页面。在如下的页面填写完参数之后执行Execute即可,还是age参数ref的问题,此时执行会提示错误,要把注释中的Integer类型去掉,在执行即可。

接下来我们看一个Get请求,这个请求不需要传参,直接执行即可,结果如下图所示。我们可以看到Swagger生成的restful形式的接口文档,非常方便调试。

接下来我们执行update的接口,这是上面我们用实体类接收参数的方法,可以看到参数的例子,我们修改完参数值后执行即可。以上swagger2与springboot就集成完了。

您可能感兴趣的文章:

内容来自用户分享和网络整理,不保证内容的准确性,如有侵权内容,可联系管理员处理 点击这里给我发消息
标签:  SpringBoot Swagger2