SpringBoot整合Swagger2

1、 SpringBoot集成Swagger2
接口文档概述:
swagger是当下比较流行的实时接口文文档生成工具。接口文档是当前前后端分离项目中必不可少的工具，在前后端开发之前，后端要先出接口文档，前端根据接口文档来进行项目的开发，双方开发结束后在进行联调测试。
所以接口文档其实就是开发之前双方之间的一种约定。通常接口文档分为离线的和实时的。离线的接口文档工具有： word(相当于没说)， YAPI, 小幺鸡等，这种文档需要程序员在上面编写，也一般具备接口测试功能。通常是由开发人员先在离线接口文档上编写信息，然后交给前端人员参照开发。最大的弊端是当我们的接口程序发生变动时，需要回过头来维护上面的内容，很麻烦，是真的麻烦。
实时接口文档就是可以根据我们的代码来自动生成相应的接口文档，优点就是我们的代码发生变化时，生成的接口文档也会自动更新，无需我们关注修改，主需要按时发布即可。但是由于是根据代码自动生成的，所以最大的弊端就是代码侵入性强，需要我们在项目代码中集成生成接口文档的相关代码。实时接口文档现在的方案有很多，但是swagger还是其中比较有影响力的一个。
① 引入依赖

 <!--添加swagger2依赖-->
        <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>

② 引入配置
首先需要添加一个注解 ： @EnableSwagger2。 这个注解我们可以添加到SpringBoot的启动类上，也可以自定义一个配置类，放到上面。添加了这个注解以后，就代表我们已经在项目中开启了Swagger的功能。
我们采用第二种方式，自己定义一个配置类，正好还可以添加一个Docket配置。 所谓Docket配置，就是一组(一个项目或一个版本)接口文档的配置，比如设置名称， 联系人等等。
我们在config文件夹下，添加一个SwaggerConfig类。如下如所示

代码如下：

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

/**
 * @PackageName: com.zpark.config
 * @ClassName: Swagger2Config
 * @Description:
 * @author: charles
 * @date: 2022/10/18  10:36
 */
@Configuration
// 开启swagger2注解功能
@EnableSwagger2
public class Swagger2Config {

    @Bean
    public Docket docket(){
        return new Docket(DocumentationType.SWAGGER_2).apiInfo(apiInfo()).select()
                .apis(RequestHandlerSelectors.basePackage("com.zpark.controller"))
                .paths(PathSelectors.any()).build();
    }

    private ApiInfo apiInfo(){
        return new ApiInfoBuilder()
                // 设置标题
                .title("这是文档描述标题")
                // 设置接口描述信息
                .description("这是swagger2接口文档")
                // 设置作者信息
                .contact(new Contact("大锤", "http://www.baidu.com", "[email protected]"))
                // 设置版本号
                .version("1.0")
                .build();
    }
}

上面就是一个配置案例， 还设置了一个setToken方法，代表生成文档的所有接口中，都要包含一个header类型的token参数
③ 给Controller 添加注解
我们接口文档的直接描述主要就是在Controller这一层，比如这个接口的功能，参数的名称，返回值的名称等。这些值我们都需要在Controller上通过给方法上，请求参数和返回参数上添加对应的注解，swagger才能帮我们生成相应的接口文档。这也就是我前面提到的对现有代码的侵入性。
我们先写一个pojo类，里边写我们的请求和相应参数，使用JavaBean定义出请求和响应的数据结构。注意这里要添加相应的注解：
pojo类

package com.zpark.pojo;

import io.swagger.annotations.ApiModel;
import io.swagger.annotations.ApiModelProperty;
import lombok.AllArgsConstructor;
import lombok.Data;
import lombok.NoArgsConstructor;
import lombok.extern.slf4j.Slf4j;

import java.util.Date;

/**
 * @Title: User
 * @Author Charles
 * @Package com.zpark.pojo
 * @Date 2022/10/18 11:00
 */
@AllArgsConstructor
@NoArgsConstructor
@Data
@Slf4j
@ApiModel("用户实体类")
public class User {
    @ApiModelProperty("用户id")
    private Integer id;
    @ApiModelProperty("用户名")
    private String username;
    @ApiModelProperty("密码")
    private String password;
    @ApiModelProperty("日期")
    private Date date;
}

这里分别使用了 @ApiModel注解和 @ApiModelProperty 注解定义了实体的名称和字段的名称，方便生成接口文档时展示。
再来看Controller:

package com.zpark.controller;

import com.zpark.pojo.User;
import io.swagger.annotations.Api;
import io.swagger.annotations.ApiImplicitParam;
import io.swagger.annotations.ApiImplicitParams;
import io.swagger.annotations.ApiOperation;
import org.springframework.web.bind.annotation.*;

/**
 * @PackageName: com.zpark.controller
 * @ClassName: Swagger2Controller
 * @Description:
 * @author: Charles
 * @date: 2022/10/18  11:04
 */
@RestController
@Api(tags = "这是swagger2接口类")
public class Swagger2Controller {

    @RequestMapping("/d1")
    @ApiOperation("这是demo01方法")
    public String demo01(){
        return "demo01方法";
    }

    @GetMapping("/d2")
    @ApiOperation("这是包含一个参数的请求方法")
    @ApiImplicitParam(name = "username", value = "用户名字", required = true, dataType = "String")
    public String demo02(String username){
        return "{这是名字："+username+"}";
    }

    @PostMapping("/d3")
    @ApiOperation("这是包含三个请求参数的方法")
    @ApiImplicitParams({
            @ApiImplicitParam(name = "uname", value = "用户名字", required = true, dataType = "String"),
            @ApiImplicitParam(name = "pwd", value = "用户密码", required = true, dataType = "String"),
            @ApiImplicitParam(name = "id", value = "用户ID", required = true)
    })
    public User demo03(String uname, String pwd, Integer id){
        return new User(id, uname, pwd, null);
    }

    @DeleteMapping("/d4")
    @ApiOperation("这是包含一个user参数的请求方法")
    @ApiImplicitParam(name = "user", value = "用户对象user", required = true)
    public User demo04(User user){
        System.out.println(user);
        return user;
    }
}

最后访问地址访问地址： ip:端口号/swagger-ui.html
结果如图所示：

到此为止，SpringBoot整和Swagger已经结束。