swagger整合

首先导入依赖

  <!--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","[email protected]"))
                //用于定义服务的域名
                //.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：用来标类
常用配置项：

1. value：实体类简称
2. description：实体类说明
   @ApiModelProperty：用来描述类的字段的意义。
   常用配置项：
3. value：字段说明
4. example：设置请求示例（Example Value）的默认值，如果不配置，当字段为string的时候，此时请
   求示例中默认值为"".
5. name：用新的字段名来替代旧的字段名。
6. 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;
}

1. required：标记字段是否必填，默认是false,
2. 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常用配置项：

1. name：用来定义参数的名字，也就是字段的名字,可以与接口的入参名对应。如果不对应，也会生成，
   所以可以用来定义额外参数！
2. value：用来描述参数
3. required：用来标注参数是否必填
4. 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;
    }

}

示例图：