Spring Boot学习(十八):Spring Boot整合Swagger2,原来这么简单

前言

Spring Boot系列: 点击查看Spring Boot系列文章



Swagger2

在现在,前后端分离已经成为互联网项目一种主流的开发方式,前端与后端交给不同的人员开发,其中交流API规定,写接口文档也成了家常便饭。我们知道,接口总是不断的在变动,如果每次都人为修改,是很浪费时间的,所以Swagger2 诞生了。Swagger2 就可以很好地解决这个问题,它可以动态生成Api接口文档,降低我们的沟通成本,最重要还免费。

1、pom文件导入依赖,我使用的是最新的2.9.2,大家根据自己需求来选择版本

        <!-- swagger依赖 -->
        <dependency>
            <groupId>io.springfox</groupId>
            <artifactId>springfox-swagger2</artifactId>
            <version>2.9.2</version>
        </dependency>
        <!-- swagger原生ui  -->
        <dependency>
            <groupId>io.springfox</groupId>
            <artifactId>springfox-swagger-ui</artifactId>
            <version>2.9.2</version>
        </dependency>

2、创建swagger2配置类,进行swagger2配置

配置很简单,只需要在配置类提供一个Docket的Bean,我们在Docket的Bean中配置swagger的信息

注:Docket中的有一个apiInfo属性,主要配置一下Swagger2文档网站的信息,例如网站的title,网站的描述,联系人的信息,使用的协议等等。

例:

@Configuration
@EnableSwagger2
public class SwaggerConfig {

    @Bean
    public Docket createRestApi() {
        return new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(apiInfo())
                //过select()函数返回一个ApiSelectorBuilder实例,用来控制哪些接口暴露给Swagger来展现
                .select()
                //api接口包扫描路径
                .apis(RequestHandlerSelectors.basePackage("com.example.demo.controller"))
                //可以根据url路径设置哪些请求加入文档,忽略哪些请求,PathSelectors.any()为全部允许
                .paths(PathSelectors.any())
                .build();
    }
    //配置在线文档的基本信息
    private ApiInfo apiInfo() {
        return new ApiInfoBuilder()
                //设置文档的标题
                .title("springboot利用swagger构建api文档")
                //设置文档的描述
                .description("api文档")
                //设置文档的版本信息
                .version("1.0")
                .build();
    }
}

@EnableSwagger2注解启用Swagger2,然后配置一个Docket Bean,这个Bean中,配置扫描接口的位置等信息。

注意:SwaggerConfig配置类最好放在和启动类同级的目录下,这样才可以扫描到我们所有想要扫描的接口

启动项目,输入http://localhost:8080/swagger-ui.html,能够看到如下页面,说明已经配置成功了

访问地址:http://项目实际地址/swagger-ui.html

在这里插入图片描述


使用Swagger2

Swagger2常用注解

@Api:用在请求的类上,说明该类的作用
tags=“说明该类的作用”

@ApiOperation:用在请求的方法上,说明方法的作用
value=“说明方法的作用”
notes=“方法的备注说明”

@ApiImplicitParams:用在请求的方法上,包含一组参数说明。@ApiImplicitParams包含多个@ApiImplicitParam

@ApiImplicitParam:用在 @ApiImplicitParams 注解中,指定一个请求参数的配置信息
name:参数名
value:参数的汉字说明、解释
required:参数是否必须传
paramType:参数放在哪个地方
· header --> 请求参数的获取:@RequestHeader
· query --> 请求参数的获取:@RequestParam
· path(用于restful接口)–> 请求参数的获取:@PathVariable
· body(不常用)
· form(不常用)
dataType:参数类型,默认String,其它值dataType=“Integer”
defaultValue:参数的默认值
例:@ApiImplicitParam(name = “id”, value = “用户ID”, required = true, dataType = “Long”,paramType = "query ");

@ApiModel:用于model类上,表示这是一个model类(一般用在使用@RequestBody传参,请求参数无法使用@ApiImplicitParam注解进行描述的时候)


@ApiModelProperty:用在属性上,描述model类的属性


@ApiResponses:用于请求的方法上,表示一组响应

@ApiResponse:用在@ApiResponses中,一般用于表达一个错误的响应信息
code:数字,例如500
message:信息,例如"代码出错"
response:抛出异常的类


使用例子

我们先创建一个User的Model类

@Data
@ApiModel(value = "用户信息")
public class User {
    @ApiModelProperty(value = "用户id")
    private Integer id;
    @ApiModelProperty(value = "用户名")
    private String username;
}

然后创建一个controller接口

@RestController
@Api(tags = "用户相关接口")
@RequestMapping("/user")
public class UserController {

    @PostMapping("/getUser")
    @ApiOperation("获取用户信息接口")
    public User getUser(){
        User user=new User();
        user.setId(1L);
        user.setUsername("m");
        return user;
    }

}

创建完成之后,我们启动项目,访问swwager网址,就可以看到接口信息了(接口请求方式,接口地址以及接口的名字等,点开一个接口,就可以看到该接口的入参和出参等信息)

在这里插入图片描述
在这里插入图片描述

除了可以查看接口信息之外,我们还可以点击右上角的Try it out,进行接口测试
在这里插入图片描述
输入入参,点击Execute,即可执行该接口

在这里插入图片描述

然后我们就可以看到响应信息了
在这里插入图片描述

评论 1
添加红包

请填写红包祝福语或标题

红包个数最小为10个

红包金额最低5元

当前余额3.43前往充值 >
需支付:10.00
成就一亿技术人!
领取后你会自动成为博主和红包主的粉丝 规则
hope_wisdom
发出的红包
实付
使用余额支付
点击重新获取
扫码支付
钱包余额 0

抵扣说明:

1.余额是钱包充值的虚拟货币,按照1:1的比例进行支付金额的抵扣。
2.余额无法直接购买下载,可以购买VIP、付费专栏及课程。

余额充值