SpringBoot的整合(四、整合Swagger2)

想必大家也搜索过Swagger的具体作用,这里不做过多阐述,简单总结一下,Swagger就是用来帮助我们整理接口信息的,我们通过Swagger提供的注解,来对接口和model进行描述。

 

下面直接上干货,springboot整合Swagger2。

(1)搭建一个springboot框架项目

首先,我们需要搭建好一个springboot的框架,如果不会搭建,可以参考我的一篇框架搭建入门文章,里面有详细的代码,希望可以帮助到大家:SpringBoot的整合(三、整合mybatis)

(2)修改pom.xml文件中

之后我们在pom.xml中添加Swagger相关的依赖

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

(3)写一个配置类

之后需要我们提供一个配置类,首先通过@EnableSwagger2注解启用Swagger2,然后配置一个Docket Bean,这个Bean中,配置映射路径和要扫描的接口的位置,在apiInfo中,主要配置一下Swagger2文档网站的信息,例如网站的title,网站的描述,联系人的信息,使用的协议等等。这样,Swagger2就算是配置成功了。要注意修改里面的扫描包的位置。位置随意。

package com.flyinghome.tm.config;

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.Contact;
import springfox.documentation.spi.DocumentationType;
import springfox.documentation.spring.web.plugins.Docket;
import springfox.documentation.swagger2.annotations.EnableSwagger2;

@Configuration
@EnableSwagger2
public class SwaggerConfig {
    @Bean
    public Docket createRestApi() {
        return new Docket(DocumentationType.SWAGGER_2)
                .pathMapping("/")
                .select()
                .apis(RequestHandlerSelectors.basePackage("com.flyinghome.tm"))
                .paths(PathSelectors.any())
                .build().apiInfo(new ApiInfoBuilder()
                        .title("SpringBoot整合Swagger测试")
                        .description("SpringBoot整合Swagger,详细信息......")
                        .version("9.0")
                        .contact(new Contact("啊啊啊啊","blog.csdn.net","aaa@gmail.com"))
                        .license("The Apache License")
                        .licenseUrl("http://www.baidu.com")
                        .build());
    }
}

我的这里是随便建了一个config文件夹放入配置类

(4)启动项目

最后启动项目,浏览器中输入:http://localhost:8080/swagger-ui.html,能够看到如下页面说明成功了。

(5)添加Swagger相关注解

此时我们开始添加注解:

首先在类上添加Api注解,方法上添加ApiOperation注解来对类和方法进行描述

@RestController
@RequestMapping(value = "/test")
@Api(tags = "用户crud测试")
public class UserController {

    @Autowired
    private UserService userService;

    /**
     * Swagger测试
     */
    @PostMapping("/testSwagger")
    @ApiOperation("Swagger的测试")
    public User getUserByid(String name,String password){
        User user = new User();
        user.setName(name);
        user.setPassword(password);
        return user;
    }
    
}

在model类中使用@ApiModelProperty注解来描述各个属性

package com.flyinghome.tm.model;

import io.swagger.annotations.ApiModelProperty;
import lombok.Data;

@Data
public class User {
    @ApiModelProperty(value = "用户id")
    private String id;
    @ApiModelProperty(value = "用户姓名")
    private String name;
    @ApiModelProperty(value = "用户密码")
    private String password;
    @ApiModelProperty(value = "页码")
    private String pageno;
    @ApiModelProperty(value = "数量")
    private String pagesize;
}

此时重新启动浏览器刷新项目,可以看到页面有了变化。即我们刚才填写的备注都显示在了对应的位置上。

(6)使用Swagger调试代码

步骤5的图中我们可以看到,在controller类中,我们有很多的接口,每个接口前面的图标即是请求的类型,可以看出图里的类中,有一个post请求和n个get请求,我们可以点击对应的接口,输入参数,进行调试。具体步骤如下:

 

(7)补充Swagger注解

Swagger的注解不仅仅是我上面所写的那些,还有一部分,下面我总结一些常用的Swagger注解,大家用来参考:

1. @Api注解可以用来标记当前Controller的功能。

2. @ApiOperation注解用来标记一个方法的作用。

3. @ApiImplicitParam注解用来描述一个参数,可以配置参数的中文含义,也可以给参数设置默认值,这样在接口测试的时候可以避免手动输入。

4. 如果有多个参数,则需要使用多个@ApiImplicitParam注解来描述,多个@ApiImplicitParam注解需要放在一个@ApiImplicitParams注解中。

5. 需要注意的是,@ApiImplicitParam注解中虽然可以指定参数是必填的,但是却不能代替@RequestParam(required = true),前者的必填只是在Swagger2框架内必填,抛弃了Swagger2,这个限制就没用了,所以假如开发者需要指定一个参数必填,@RequestParam(required = true)注解还是不能省略。

6. 如果参数是一个对象(例如上文的更新接口),对于参数的描述也可以放在实体类中。

 

参考:

1. https://blog.csdn.net/u012702547/article/details/88775298

2. https://blog.csdn.net/miachen520/article/details/95722887

持续更新!!!

 

posted @ 2020-05-23 22:31  夏夜凉凉  阅读(4326)  评论(0编辑  收藏