springboot集成Swagger2

概述

Swagger能帮助我们自动生成所有接口的文档，以及测试每个接口的框架。现在大部分项目都是前后台分离的，后台调试接口的时候很多同学都会使用postman，有了Swagger，我们可以直接进行
接口测试，不用postman等工具了。而且还可以给前端人员提供一个接口文档，方便前端人员查看接口的参数以及返回值信息。接口信息发生变化后，Swagger会自动更新接口信息，不用我们专门
提供一个文档来维护。没有使用swagger的时候，API版本每次更新的时候，都需要再次发送一份给前端，前端有时候没有看到，容易造成文档交流不及时，产生误会
，有时候还会闹个小矛盾，影响大家的心情。

Swagger优缺点

• 优点
  • 不用手写接口文档，会自动生成接口文档，保证前台第一时间拿到最新接口文档
  • 通过注解灵活的自动的生成在线文档
  • 接口还可以在线调用调试，不用再使用postman等工具
• 缺点
  • 代码耦合度高，需要注解支持
  • 代码侵入性比较强

集成

1. 引入jar包

<!-- Swagger 所需jar -->
<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>

2. 创建Swagger2Config配置

@Configuration
@EnableSwagger2
public class Swagger2Config {
    @Value("${swagger.enable}")
    private boolean enableSwagger;
    /**
     * swagger2的配置文件，这里可以配置swagger2的一些基本的内容，比如扫描的包等等
     * @return
     */
    @Bean
    public Docket createRestApi() {
        return new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(apiInfo())
                //是否开启swagger
                .enable(enableSwagger)
                .select()
                //此包路径下的类，才生成接口文档
                .apis(RequestHandlerSelectors.basePackage("com.moyundong"))
                //加了ApiOperation注解的类，才生成接口文档
                .apis(RequestHandlerSelectors.withMethodAnnotation(ApiOperation.class))
                .paths(PathSelectors.any())
                .build();
    }
    private ApiInfo apiInfo() {
        return new ApiInfoBuilder()
            //设置文档大标题
            .title("java乐园后台服务API接口文档")
            // 版本号
            .version("1.0")
            // 描述
            .description("restful 风格接口")
            //服务条款URL
            .termsOfServiceUrl("http://www.moyundong.com")
            // 作者信息
            .contact(new Contact("牛魔王", "http://www.moyundong.com", "945447276@qq.com"))
            .build();
    }
}

• @Configuration标注在类上，相当于把该类作为spring的xml配置文件中的，第9节内容有介绍。
• @EnableSwagger2的作用是启用Swagger2相关功能。
• 配置文件就是这个固定写法，大家看注释基本都能明白。里面要注意的是扫描的包路径，只有扫描的路径下的类才能自动生成文档。我们一般就是在controller里面使用swagger
• 我们在Swagger2Config配置里面添加了enableSwagger，用来自定义开启swagger，enableSwagger的赋值是在application.yml配置文件里面。

3. 创建测试类SysUserController，测试类里面包含了增删改查方法

@RestController
@RequestMapping("sysUser")
@Api(value = "测试接口", tags = "用户测试接口")
public class SysUserController {

    @GetMapping("user/{id}")
    @ApiOperation(value = "查询用户信息1", notes = "查询用户信息1的notes信息")
    public String selectById(@PathVariable(name = "id") String id){
        System.out.println("参数id="+id);
        return "selectById请求成功";
    }

    @GetMapping("selectById")
    @ApiOperation(value = "查询用户信息2", notes = "查询用户信息2的notes信息")
    public String selectById2(@RequestParam(name = "id") String id){
        System.out.println("参数id="+id);
        return "selectById2请求成功";
    }

    @PostMapping(path = "/addUser")
    @ApiOperation(value = "新增用户信息", notes = "新增用户信息的notes信息")
    public String addUser(@RequestBody SysUser sysUser) {
        System.out.println(sysUser.toString());
        return "addUser请求成功";
    }

    @DeleteMapping("deleteById")
    @ApiOperation(value = "根据id删除用户", notes = "根据id删除用户的notes信息")
    public String deleteById(@RequestParam(name = "id") String id){
        System.out.println("参数id="+id);
        return "deleteById请求成功";
    }

    @PutMapping(path = "/editUser")
    @ApiOperation(value = "修改用户信息", notes = "修改用户信息的notes信息")
    public String editUser(@RequestBody SysUser sysUser) {
        System.out.println(sysUser.toString());
        return "edit请求成功";
    }
}

4. 创建测试用实体SysUser

@Data
public class SysUser {
    private String id;
    private String username;
    private String password;
    private Date birthday;
    private String email;
}

5. 启动项目，再浏览器输入：http://localhost:8088/moyundong/swagger-ui.html，就会看到如下界面
   
   ::: tip 提示
   如果在配置文件里面关闭swagger，那么页面就会出现Could not render e, see the console.
   :::

使用

1. 点击某个类

[外链图片转存失败,源站可能有防盗链机制,建议将图片保存下来直接上传(img-kdyTe4Qh-1594132992718)(http://47.94.137.150/moyundong/image/java/springboot2/springboot2-12-2.png)]

2. 选择要测试的方法，然后点击try it

[外链图片转存失败,源站可能有防盗链机制,建议将图片保存下来直接上传(img-cAZYIrMZ-1594132992721)(http://47.94.137.150/moyundong/image/java/springboot2/springboot2-12-3.png)]

3. 测试参数swagger已经帮我们默认设置好了，我们也可以自定义修改，然后点击执行

[外链图片转存失败,源站可能有防盗链机制,建议将图片保存下来直接上传(img-7s4UeeAM-1594132992725)(http://47.94.137.150/moyundong/image/java/springboot2/springboot2-12-4.png)]

4. 查看执行结果

[外链图片转存失败,源站可能有防盗链机制,建议将图片保存下来直接上传(img-7L35exoT-1594132992726)(http://47.94.137.150/moyundong/image/java/springboot2/springboot2-12-5.png)]

参数详解

• @Api:用于controller类上，说明该类的作用，示例@Api(value = "测试接口", tags = "用户测试接口")

value: 经过测试，发现在当前使用方法的情况下没有作用
tags：可以在UI界面上看到作用在controller上的注释

• @ApiOperation：用在controller的方法上，用来说明方法用途、作用

value=说明方法的用途、作用，方法折叠起来的时候也能看见
notes=方法的备注说明，点开方法明细里面显示

• @ApiImplicitParam：用来给方法入参增加说明

name：参数名
value：参数的汉字说明、解释
dataType： 参数类型，默认String
required ： 参数是否必传，true必传
defaultValue：参数的默认值
paramType：参数放在哪个地方
header请求参数的获取:@RequestHeader,参数从请求头获取
query请求参数的获取:@RequestParam,参数从地址栏问号后面的参数获取
path（用于restful接口）请求参数的获取：@PathVariable，参数从URL地址上获取
body（不常用）参数从请求体中获取
form（不常用）参数从form表单中获取

• @ApiImplicitParams：用在controller的方法上，一组@ApiImplicitParam
• @ApiResponse：用在 @ApiResponses里边，一般用于表达一个错误的响应信息

code：数字，例如400
message：信息，例如"请求参数没填好"
response：抛出异常的类

• @ApiResponses：用在controller的方法上，用于表示一组响应
• @ApiModel：用在返回对象类上，描述一个Model的信息（这种一般用在post创建的时候，使用@RequestBody这样的场景，请求参数无法使用@ApiImplicitParam注解进行描述的时候）
• @ApiModelProperty：用在出入参数对象的字段上，表示对model属性的说明或者数据操作更改

value = 字段说明
name = 重写属性名字
dataType = 重写属性类型
required = 是否必填，true必填
example = 举例说明
hidden = 隐藏

• @ApiIgnore：使用该注解忽略这个API，不会生成接口文档。可注解在类和方法上
  ::: warning 注意
  swagger里面注解很多，我们最好不要使用过多，一般建议使用最基本的@Api和@ApiOperation就可以了。其它看个人情况慎重使用。
  :::

本节示例下载地址：java相关demo下载列表

1介绍
2springboot定时任务
3springboot定时任务配置详解
4springboot动态定时任务
5springboot集成websocket
6springboot多数据源
7springboot配置druid监听
8springboot自定义注解
9springboot常见注解详解
10springboot接收参数详解
11springboot验证机制@Valid和@Validated
12springboot集成Swagger2
13springboot集成swagger-bootstrap-ui
14springboot集成shiro
15springboot集成shiro（二）
16springboot集成jwt
17springboot集成ActiveMQ
18springboot缓存机制

🍉🍉🍉 欢迎大家来博客了解更多内容：java乐园 🍉🍉🍉