springboot整合swagger
中国加油，武汉加油
项目准备
- 创建项目nz1904-springboot-04-swagger
- 导依赖
<!--导包--> <dependency> <groupId>io.springfox</groupId> <artifactId>springfox-swagger2</artifactId> <version>2.7.0</version> </dependency> <dependency> <groupId>io.springfox</groupId> <artifactId>springfox-swagger-ui</artifactId> <version>2.7.0</version> </dependency>
1. 案例
1.1 写一个Swagger配置类
package com.wpj.config;
import org.springframework.boot.SpringBootConfiguration;
import org.springframework.context.annotation.Bean;
import springfox.documentation.builders.ApiInfoBuilder;
import springfox.documentation.builders.PathSelectors;
import springfox.documentation.builders.RequestHandlerSelectors;
import springfox.documentation.service.ApiInfo;
import springfox.documentation.spi.DocumentationType;
import springfox.documentation.spring.web.plugins.Docket;
import springfox.documentation.swagger2.annotations.EnableSwagger2;
@SpringBootConfiguration
@EnableSwagger2 //使能Swagger
public class SwaggerConfig {
@Bean
public Docket docket(){
return new Docket(DocumentationType.SWAGGER_2)
.apiInfo(apiInfo()) // 生成接口室页面显示的信息
.select() // 表示是否选择那些路径和API生成文档
.apis(RequestHandlerSelectors.basePackage("com.wpj.controller")) // 告诉他要扫描的接口存在的这个包
.paths(PathSelectors.any()) // 对所有API进行监控
.build(); // 构建
}
/**
* 主要作用是显示页面上的信息
* @return
*/
private ApiInfo apiInfo() {
return new ApiInfoBuilder()
.title("这里是测试Swagger2的功能文档") //文档的标题
.description("这里是nz1904-springboot-04-swagger测试用的") //描述
.contact("杰KaMi") // 作者
.version("v1.0") // 版本
.build();
}
}
1.2 创建controller包
1.3 修改默认的主启动类
可不做，注意包结构
package com.wpj;
import org.springframework.boot.SpringApplication;
import org.springframework.boot.autoconfigure.SpringBootApplication;
@SpringBootApplication
public class Application {
public static void main(String[] args) {
SpringApplication.run(Application.class, args);
}
}
1.4 启动项目并访问浏览器测试
2. 扩展
2.0.5 定义一个返回结果的类
package com.wpj.result;
import lombok.AllArgsConstructor;
import lombok.Data;
import lombok.NoArgsConstructor;
@Data
@AllArgsConstructor
@NoArgsConstructor
public class RespResult<T> {
private int code;
private String msg;
private T data;
public RespResult(int code, String msg) {
this.code = code;
this.msg = msg;
}
}
2.1 无参方法
package com.wpj.controller;
import com.wpj.result.RespResult;
import io.swagger.annotations.*;
import org.springframework.web.bind.annotation.RequestMapping;
import org.springframework.web.bind.annotation.RequestMethod;
import org.springframework.web.bind.annotation.RequestParam;
import org.springframework.web.bind.annotation.RestController;
/**
* 用户控制器
*/
@RestController
@Api(tags = {"这个是用户的控制器"}) // 说明当前的Controller作用
public class UserController {
/**
* 没有参数的玩法
* @return
*/
@RequestMapping(value = "/test", method = RequestMethod.GET)
@ApiOperation(value = "测试接口1",notes="调用当前方法的注意事项")
public RespResult<String> test1(){
RespResult<String> result = new RespResult<>();
result.setCode(1);
result.setMsg("请求成功");
result.setData("xxxxxxxxxxxxxxxxxxxxx");
return result;
}
}
2.2 简单参数方法
/**
* 简单参数的方法
* ApiImplicitParam注解
* header：请求的数据放在请求头
* query：请求参数放在请求地址上
* path：(RestFul中用于面向资源编程的获取数据的方式，配套的获取数据的注解 @PathVarible)
* body：不会用
* form：基本不用
* @return
*/
@RequestMapping(value = "/test2", method = RequestMethod.GET)
@ApiOperation(value = "测试接口2",notes="调用当前方法的注意事项")
/**
* paramType: 类型
* name: 说明的是参数的名字叫什么
* value: 当前参数含义
* required: 当前使用接口参数是否一定要传
* dataType: 参数的类型
*/
// @ApiImplicitParam(paramType="query", name="name", value="名字", required = true, dataType = "String")
/**
* ApiImplicitParam注解 和 ApiParam 是一样的，但是ApiParam更强大，相当于ApiImplicitParam的升级版
*/
@ApiParam(name = "name", value = "名字", required = true)
public RespResult<String> test2(@RequestParam("name") String name){
RespResult<String> result = new RespResult<>();
result.setCode(1);
result.setMsg("请求成功");
result.setData(name);
return result;
}
2.3 多个参数方法
/**
* 多个参数方法
* @param name
* @param pwd
* @return
*/
@RequestMapping(value = "/test3", method = RequestMethod.GET)
@ApiOperation(value = "测试接口3",notes="调用当前方法的注意事项")
@ApiImplicitParams({
@ApiImplicitParam(paramType="query", name="name", value="名字", required = true, dataType = "String"),
@ApiImplicitParam(paramType="query", name="pwd", value="密码", required = true, dataType = "String")
})
@ApiResponse(code = 0, message = "请求成功")
public RespResult<String> test3(@RequestParam("name") String name,@RequestParam("pwd") String pwd){
RespResult<String> result = new RespResult<>();
result.setCode(1);
result.setMsg("请求成功");
result.setData(name+" : "+ pwd);
return result;
}
2.4 对象参数方法
2.4.1 定义一个对象
package com.wpj.pojo;
import io.swagger.annotations.ApiModel;
import io.swagger.annotations.ApiModelProperty;
import lombok.AllArgsConstructor;
import lombok.Data;
import lombok.NoArgsConstructor;
@Data
@AllArgsConstructor
@NoArgsConstructor
@ApiModel(value = "用户对象")
public class User {
@ApiModelProperty(value="用户id")
private int id;
@ApiModelProperty(value="名字")
private String name;
@ApiModelProperty(value="密码")
private String pwd;
}
2.4.2 对象参数方法
@RequestMapping(value = "/test4", method = RequestMethod.POST)
@ApiOperation(value = "测试接口4",notes="调用当前方法的注意事项")
@ApiResponse(code = 0, message = "请求成功")
public RespResult<User> test4(@RequestBody User user){
RespResult<User> result = new RespResult<>();
result.setCode(1);
result.setMsg("请求成功");
result.setData(user);
return result;
}
2.4.3 支持token传输
/**
* 对象参数方法
* @param user
* @return
*/
@RequestMapping(value = "/test4", method = RequestMethod.POST)
@ApiOperation(value = "测试接口4",notes="调用当前方法的注意事项")
@ApiImplicitParam(paramType = "header", name = "token", value = "用户token", required = true, dataType = "String")
public RespResult<User> test4(@RequestBody User user, HttpServletRequest request){
String token = request.getHeader("token");
RespResult<User> result = new RespResult<>();
result.setCode(1);
result.setMsg("请求成功" + " : " + token);
result.setData(user);
return result;
}
2.5 文件上传
/**
* 文件上传
* @param uId
* @param multipartFile
* @return
*/
@RequestMapping(value = "/test5", method = RequestMethod.POST)
@ApiOperation(value = "测试接口4",notes="调用当前方法的注意事项")
@ApiImplicitParams({
@ApiImplicitParam(paramType = "header", name = "token", value = "用户token", required = true, dataType = "String"),
@ApiImplicitParam(paramType = "query", name = "uId", value = "用户ID", required = true, dataType = "Integer")
})
public RespResult<String> test5(@RequestParam("uId") int uId,@RequestParam("file") MultipartFile multipartFile){
RespResult<String> result = new RespResult<>();
//文件另存
try {
multipartFile.transferTo(new File("D://jiekami.jpg"));
result.setCode(1);
result.setMsg("请求成功" + " : " + multipartFile.getOriginalFilename());
result.setData("上传成功。");
} catch (IOException e) {
result.setCode(0);
result.setMsg("请求失败" + " : " + e.getMessage());
result.setData("上传失败 。");
}
return result;
}
3. 常用的注解
@Api ：这个注解的主要功能是描述当前的Controller是用来干嘛的
@ApiOperation ：这个注解的主要功能是说明当前接口的作用
@ApiImplicitParam ：这个的主要功能是接口的参数说明
@ApiImplicitParams ：多参数的时候使用 参数的说明
@ApiParam ：主要功能也是接口的参数说明
@ApiModel ：主要就是对接口中传输的对象的说明
@ApiModelProperty ：这个是接口参数对象中的成员变量的说明
@Apiresponse ：返回结果的说明
