第一步:引入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