首先导入依赖
<!--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>
要使用swagger,我们必须对swagger进行配置,我们需要创建一个swagger的配置类,比如可以命名为
SwaggerConfig.java
package com.example.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;
/*
* 用于配置SwaggerApi
* */
//开启Swagger使用(项目注释文档)
@EnableSwagger2
//标明是配置类
@Configuration
public class SwaggerConfig {
@Bean
public Docket createRestApi() {
return new Docket(DocumentationType.SWAGGER_2)
//用于生成API信息
.apiInfo(apiInfo())
//select()函数返回一个ApiSelectorBuilder实例,用来控制接口被swagger做成文档
.select()
//用于指定扫描哪个包下的接口
.apis(RequestHandlerSelectors.basePackage("com.example.controller"))
//选择所有的API,如果你想只为部分API生成文档,可以配置这里
.paths(PathSelectors.any())
.build();
}
/*
*用于定义API主界面的信息,比如可以声明所有的API的总标题、描述、版本
*/
private ApiInfo apiInfo() {
return new ApiInfoBuilder()
//用来自定义API的标题
.title("Hello SwaggerAPI")
//用来描述整体的API
.description("我想在这里描述点啥,但是又不知道说些什么?")
//创建人信息
.contact(new Contact("lixp","http://localhost:8082/swagger-ui.html","xxxxxxxx@163.com"))
//用于定义服务的域名
//.termsOfServiceUrl("")
.version("1.0") //可以用来定义版本
.build();
}
}
配置文件添加(SpringBoot2.5以上都需要添加)
spring:
mvc:
pathmatch:
matching-strategy: ant_path_matcher
运行我们的Spring Boot项目,(我的8080端口被占用了,如果你不一样,请注意修改后续的url),
访问http://localhost:8082/swagger-ui.html
然后你就可以看到一个如下的界面,由于我们暂时没有配置接口数据,所以下面显示No operations defined
in spec!
定义组接口
使用了 @Api 来标注一个Controller之后,如果下面有接口,那么就会默认生成文档,但没有我们自定义的说
明:
package com.its.swagger.controller;
import io.swagger.annotations.Api;
import org.springframework.web.bind.annotation.GetMapping;
import org.springframework.web.bind.annotation.RestController;
@Api(tags = "用户管理")
@RestController
public class UserController {
// 注意,对于swagger,不要使用@RequestMapping,
// 因为@RequestMapping支持任意请求方式,swagger会为这个接口生成7种请求方式的接口文档
@GetMapping("/info")
public String info(String id){
return "aaa";
}
}
package com.its.swagger.controller;
import io.swagger.annotations.Api;
import org.springframework.web.bind.annotation.PostMapping;
import org.springframework.web.bind.annotation.RestController;
@Api(tags = "角色管理") // tags:你可以当作是这个组的名字。
@RestController
public class RoleController {
@PostMapping("/ww")
public boolean ww(){
return false;
}
}
重启查看UI视图
视图解析
我们可以使用 @ApiOperation 来描述接口,比如:
@ApiOperation(value = "用户测试",notes = "用户测试notes")
@GetMapping("/test")
public String test(String id){
return "test";
}
定义接口请求参数
上面使用了@ApiOperation来了描述接口,但其实还缺少接口请求参数的说明,下面我们分场景来讲。
注意一下,对于GET方式,swagger不推荐使用body方式来传递数据,也就是不希望在GET方式时使用
json、form-data等方式来传递,这时候最好使用路径参数或者url参数。(虽然POSTMAN等是支持的),所以
如果接口传递的数据是json或者form-data方式的,还是使用POST方式好。
请求参数是实体类
此时我们需要使用 @ApiModel 来标注实体类,然后在接口中定义入参为实体类即可:
@ApiModel:用来标类
常用配置项:
- value:实体类简称
- description:实体类说明
@ApiModelProperty:用来描述类的字段的意义。
常用配置项: - value:字段说明
- example:设置请求示例(Example Value)的默认值,如果不配置,当字段为string的时候,此时请
求示例中默认值为"". - name:用新的字段名来替代旧的字段名。
- allowableValues:限制值得范围,例如{1,2,3}代表只能取这三个值;[1,5]代表取1到5的值;(1,5)代表1
到5的值,不包括1和5;还可以使用infinity或-infinity来无限值,比如[1, infinity]代表最小值为1,最大
值无穷大。
public class Filter {
@ApiModelProperty(allowableValues = "range[1,5]")
Integer order
@ApiModelProperty(allowableValues = "111, 222")
String code;
}
- required:标记字段是否必填,默认是false,
- hidden:用来隐藏字段,默认是false,如果要隐藏需要使用true,因为字段默认都会显示,就算没有
@ApiModelProperty。
package com.its.swagger.pojo;
import io.swagger.annotations.ApiModel;
import io.swagger.annotations.ApiModelProperty;
import lombok.Data;
// 先使用@ApiModel来标注类
@ApiModel(value="用户登录表单对象",description="用户登录表单对象")
@Data //getter,setter,swagger也需要这个
public class LoginForm {
// 使用ApiModelProperty来标注字段属性。
@ApiModelProperty(value = "用户名",required = true,example = "root")
private String username;
@ApiModelProperty(value = "密码",required = true,example = "123456")
private String password;
}
定义成入参
@ApiOperation(value = "登录接口",notes = "登录接口的说明")
@PostMapping("/login")
public LoginForm login(@RequestBody LoginForm loginForm){
return loginForm;
}
请求参数是非实体类
声明入参是URL参数
再说一次:对于GET方式,swagger不推荐使用body方式来传递数据,所以虽然Spring MVC可以自动封装参
数,但对于GET请求还是不要使用form-data,json等方式传递参数,除非你使用Postman来测试接口,
swagger在线测试是不支持这个操作的。
对于非实体类参数,可以使用@ApiImplicitParams和@ApiImplicitParam来声明请求参数。
@ApiImplicitParams用在方法头上,@ApiImplicitParam定义在@ApiImplicitParams里面,一个
@ApiImplicitParam对应一个参数。
@ApiImplicitParam常用配置项:
- name:用来定义参数的名字,也就是字段的名字,可以与接口的入参名对应。如果不对应,也会生成,
所以可以用来定义额外参数! - value:用来描述参数
- required:用来标注参数是否必填
- paramType有path,query,body,form,header等方式,但对于对于非实体类参数的时候,常用的只有
path,query,header;body和form是不常用的。body不适用于多个零散参数的情况,只适用于json对
象等情况。【如果你的接口是form-data,x-www-form-urlencoded的时候可能不能使用swagger页面
API调试,但可以在后面讲到基于BootstrapUI的swagger增强中调试,基于BootstrapUI的swagger支
持指定form-data或x-www-form-urlencoded】
// 使用URL query参数
@ApiOperation(value = "登录接口2",notes = "登录接口的说明2")
@ApiImplicitParams({
@ApiImplicitParam(name = "username",//参数名字
value = "用户名",//参数的描述
required = true,//是否必须传入
//paramType定义参数传递类型:有path,query,body,form,header
paramType = "query"
)
,
@ApiImplicitParam(name = "password",//参数名字
value = "密码",//参数的描述
required = true,//是否必须传入
paramType = "query"
)
})
@PostMapping(value = "/login2")
public LoginForm login2(String username,String password){
System.out.println(username+":"+password);
LoginForm loginForm = new LoginForm();
loginForm.setUsername(username);
loginForm.setPassword(password);
return loginForm;
}
声明入参是URL路径参数
// 使用路径参数
@PostMapping("/login3/{id1}/{id2}")
@ApiOperation(value = "登录接口3",notes = "登录接口的说明3")
@ApiImplicitParams({
@ApiImplicitParam(name = "id1",//参数名字
value = "用户名",//参数的描述
required = true,//是否必须传入
//paramType定义参数传递类型:有path,query,body,form,header
paramType = "path"
)
,
@ApiImplicitParam(name = "id2",//参数名字
value = "密码",//参数的描述
required = true,//是否必须传入
paramType = "path"
)
})
public String login3(@PathVariable Integer id1,@PathVariable Integer id2){
return id1+":"+id2;
}
声明入参是header参数:
// 用header传递参数
@PostMapping("/login4")
@ApiOperation(value = "登录接口4",notes = "登录接口的说明4")
@ApiImplicitParams({
@ApiImplicitParam(name = "username",//参数名字
value = "用户名",//参数的描述
required = true,//是否必须传入
//paramType定义参数传递类型:有path,query,body,form,header
paramType = "header"
)
,
@ApiImplicitParam(name = "password",//参数名字
value = "密码",//参数的描述
required = true,//是否必须传入
paramType = "header"
)
})
public String login4( @RequestHeader String username,
@RequestHeader String password){
return username+":"+password;
}
声明文件上传参数
// 有文件上传时要用@ApiParam,用法基本与@ApiImplicitParam一样,不过@ApiParam用在参数上
// 或者你也可以不注解,swagger会自动生成说明
@ApiOperation(value = "上传文件",notes = "上传文件")
@PostMapping(value = "/upload")
public String upload(@ApiParam(value = "图片文件", required = true)MultipartFile
uploadFile){
String originalFilename = uploadFile.getOriginalFilename();
return originalFilename;
}
// 多个文件上传时,**swagger只能测试单文件上传**
@ApiOperation(value = "上传多个文件",notes = "上传多个文件")
@PostMapping(value = "/upload2",consumes = "multipart/*", headers = "contenttype=multipart/form-data")
public String upload2(@ApiParam(value = "图片文件", required = true,allowMultiple =
true)MultipartFile[] uploadFile){
StringBuffer sb = new StringBuffer();
for (int i = 0; i < uploadFile.length; i++) {
System.out.println(uploadFile[i].getOriginalFilename());
sb.append(uploadFile[i].getOriginalFilename());
sb.append(",");
}
return sb.toString();
}
// 既有文件,又有参数
@ApiOperation(value = "既有文件,又有参数",notes = "既有文件,又有参数")
@PostMapping(value = "/upload3")
@ApiImplicitParams({
@ApiImplicitParam(name = "name",
value = "图片新名字",
required = true
)
})
public String upload3(@ApiParam(value = "图片文件", required = true)MultipartFile
uploadFile,
String name){
String originalFilename = uploadFile.getOriginalFilename();
return originalFilename+":"+name;
}
定义接口响应
定义接口响应,是方便查看接口文档的人能够知道接口返回的数据的意义。
响应是实体类
前面在定义接口请求参数的时候有提到使用 @ApiModel 来标注类,如果接口返回了这个类,那么这个类上的
说明也会作为响应的说明:
// 返回被@ApiModel标注的类对象
@ApiOperation(value = "实体类响应",notes = "返回数据为实体类的接口")
@PostMapping("/role1")
public LoginForm role1(@RequestBody LoginForm loginForm){
return loginForm;
}
响应是非实体类
swagger无法对非实体类的响应进行详细说明,只能标注响应码等信息。是通过 @ApiResponses 和
@ApiResponse 来实现的。
@ApiResponses 和 @ApiResponse 可以与 @ApiModel 一起使用。
// 其他类型的,此时不能增加字段注释,所以其实swagger推荐使用实体类
@ApiOperation(value = "非实体类",notes = "非实体类")
@ApiResponses({
@ApiResponse(code=200,message = "调用成功"),
@ApiResponse(code=401,message = "无权限" )
}
)
@PostMapping("/role2")
public String role2(){
return " {\n" +
" name:\"广东\",\n" +
" citys:{\n" +
" city:[\"广州\",\"深圳\",\"珠海\"]\n" +
" }\n" +
" }";
}
Swagger UI增强
你可能会觉得现在这个UI不是很好看,现在有一些第三方提供了一些Swagger UI增强,比较流行的是
swagger-bootstrap-ui
<!-- 引入swagger-bootstrap-ui依赖包-->
<dependency>
<groupId>com.github.xiaoymin</groupId>
<artifactId>swagger-bootstrap-ui</artifactId>
<version>1.9.6</version>
</dependency>
在swagger配置类中增加注解 @EnableSwaggerBootstrapUI :
@Configuration // 标明是配置类
@EnableSwagger2 //开启swagger功能
@EnableSwaggerBootstrapUI // 开启SwaggerBootstrapUI
public class SwaggerConfig {
// 省略配置内容
}
访问API: http://localhost:8080/doc.html ,即可预览到基于bootstarp的Swagger UI界面。
最后我写了swagger的增删改查以及文件上传代码示例如下:
package com.example.controller;
import com.example.pojo.Cargo;
import com.example.service.CargoService;
import io.swagger.annotations.Api;
import io.swagger.annotations.ApiImplicitParam;
import io.swagger.annotations.ApiImplicitParams;
import io.swagger.annotations.ApiOperation;
import org.springframework.beans.factory.annotation.Autowired;
import org.springframework.web.bind.annotation.*;
import org.springframework.web.multipart.MultipartFile;
import java.io.File;
import java.io.IOException;
import java.util.List;
/**
* <p>
* 前端控制器
* </p>
*
* @author lixp
* @since 2023年04月10日
*/
@Api(tags = "李小屁的专属")
@RestController
@RequestMapping("/cargo")
public class CargoController {
@Autowired
private CargoService cargoService;
// 查所有
@ApiOperation(value = "查询所有",notes = "查所有")
@ApiImplicitParams({
@ApiImplicitParam(name = "username",
value = "用户名",
required = true,
paramType = "query")
})
@GetMapping
public List<Cargo> list() {
return cargoService.list();
}
// 根据id查询
@GetMapping("/{id}")
public Cargo getById(@PathVariable Long id){
return cargoService.getById(id);
}
// 删除
@DeleteMapping
public boolean delete(@RequestParam Long id){
return cargoService.removeById(id);
}
//修改
@PutMapping
public boolean update(Cargo cargo) {
return cargoService.updateById(cargo);
}
// 文件上传
@ApiOperation("文件上传")
@PostMapping("/upload")
public boolean upload(MultipartFile multipartFile) throws IOException {
multipartFile.transferTo(new File("D:\\images\\"+multipartFile.getOriginalFilename()));
return true;
}
}
示例图: