Spring Boot整合Swagger3

第一步：引入SpringBoot整合Swagger2的最版版本3.0.0，目前的更新时间为2020年7月

<!--引入SpringBoot整合Swagger3的依赖-->
<dependency>
    <groupId>io.springfox</groupId>
    <artifactId>springfox-boot-starter</artifactId>
    <version>3.0.0</version>
</dependency>

其依赖包的目录结构如下：

 第二步：构建Swagger3的配置类

import io.swagger.annotations.ApiOperation;
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;

@Configuration
public class Swagger3Config {
    @Bean
    public Docket createRestApi() {
        return new Docket(DocumentationType.OAS_30)
                .apiInfo(apiInfo())
                .select()
                .apis(RequestHandlerSelectors.withMethodAnnotation(ApiOperation.class))
                //指定需要扫描的包路径，只有此路径下的 Controller 类才会自动生成 Swagger API 文档
                .apis(RequestHandlerSelectors.basePackage("com.bc.work.controller"))
                .paths(PathSelectors.any())
                .build();
    }

    private ApiInfo apiInfo() {
        return new ApiInfoBuilder()
                .title("Swagger3接口文档")
                .description("接口文档描述部分")
                .contact(new Contact("bc", "http://www.baidu.com", "123456@qq.com"))
                .version("1.0版本")
                .build();
    }
}

第三步：下面主要是Swagger3注解使用说明

@Api：用在请求类上，其tags属性表示说明该类有什么作用

import io.swagger.annotations.Api;
import io.swagger.annotations.ApiOperation;
import org.springframework.web.bind.annotation.GetMapping;
import org.springframework.web.bind.annotation.RequestMapping;
import org.springframework.web.bind.annotation.RestController;

@Api(tags = "用户管理")
@RestController
@RequestMapping("/user")
public class UserController {

    @ApiOperation("获取用户信息")
    @GetMapping("/getInfo")
    public String getInfo() {
        return "{\"name\":\"张三\",\"age\":\"18\"}";
    }
}

@ApiOperation：用在请求方法上，其value属性表示该方法的作用，notes属性表示方法的备注

import io.swagger.annotations.Api;
import io.swagger.annotations.ApiOperation;
import org.springframework.web.bind.annotation.GetMapping;
import org.springframework.web.bind.annotation.RequestMapping;
import org.springframework.web.bind.annotation.RestController;

@Api(tags = "用户管理")
@RestController
@RequestMapping("/user")
public class UserController {

    @ApiOperation(value = "获取用户信息",notes="获取用户基本的信息，仅包含姓名和年龄")
    @GetMapping("/getInfo")
    public String getInfo() {
        return "{\"name\":\"张三\",\"age\":\"18\"}";
    }
}

@ApiImplicitParams：用在请求方法上，表示一组参数说明

@ApiImplicitParam：用在@ApiImplicitParams注解中，指定一个请求参数的各个方面，其各个属性字段如下：

name：参数名
value：参数的汉字说明、解释
required：参数是否必须传
paramType：参数放在哪个地方
    · header --> 请求参数的获取：@RequestHeader
    · query  --> 请求参数的获取：@RequestParam
    · path   --> 请求参数的获取：@PathVariable
    . body   --> 请求参数的获取：@RequestBody
    . form（不建议使用）
dataType：参数类型，默认"String"，其它值dataType="Integer"       
defaultValue：参数的默认值

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.GetMapping;
import org.springframework.web.bind.annotation.RequestMapping;
import org.springframework.web.bind.annotation.RequestParam;
import org.springframework.web.bind.annotation.RestController;

@Api(tags = "用户管理")
@RestController
@RequestMapping("/user")
public class UserController {

    @ApiOperation(value = "获取用户信息",notes="获取用户基本的信息，仅包含姓名和年龄")
    @ApiImplicitParams(
            @ApiImplicitParam(name = "name",value = "姓名",required = true,paramType = "query",dataType = "String")
    )
    @GetMapping("/getInfo")
    public String getInfo(@RequestParam(name = "name") String name) {
        return "{\"name\":\""+name+"\",\"age\":\"18\"}";
    }
}

@ApiResponses：用在请求的方法上，表示一组响应
@ApiResponse：用在@ApiResponses中，一般用于表达一个错误的响应信息
        code：数字，例如400
        message：信息，例如"请求参数没填好"
        response：抛出异常的类

上述两个注解目前未使用到

@ApiModel：用在响应类上，表示一个返回响应数据的信息

@ApiModelProperty：用在响应类的属性上，value属性表示该响应字段是什么意思

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

@ApiModel
@Data
public class UserVo {

    @ApiModelProperty(value = "姓名")
    private String name;

    @ApiModelProperty(value = "年龄")
    private String age;
}

import com.bc.work.vo.UserVo;
import io.swagger.annotations.Api;
import io.swagger.annotations.ApiOperation;
import org.springframework.web.bind.annotation.GetMapping;
import org.springframework.web.bind.annotation.RequestMapping;
import org.springframework.web.bind.annotation.RestController;

@Api(tags = "用户管理")
@RestController
@RequestMapping("/user")
public class UserController {

    @ApiOperation(value = "获取用户信息",notes="获取用户基本的信息，仅包含姓名和年龄")
    @GetMapping("/getInfo")
    public UserVo getInfo() {
        UserVo userVo=new UserVo();
        userVo.setName("张三");
        userVo.setAge("18");
        return userVo;
    }
}

第四步：下述两个访问地址都可以访问到Swagger3接口文档界面：

http://127.0.0.1:9865/swagger-ui/
http://127.0.0.1:9865/swagger-ui/index.html

生产环境中，一般Swagger文档是需要关闭的，不能对外开放，因此可在配置文件(application.yml)做下述配置：

#对外关闭Swagger文档
springfox:
  documentation:
    swagger-ui:
      enabled: false