本文不是对Swagger的学习，只是记录如何配置Swagger
简单学习Swagger可以看这篇博文：swagger使用指南
Swagger Api注解速览
@Api： 用于类，标识这个类是swagger的资源
@ApiIgnore： 用于类，忽略该 Controller，指不对当前类做扫描
@ApiOperation： 用于方法，描述 Controller类中的 method接口
@ApiParam： 用于参数，单个参数描述，与 @ApiImplicitParam不同的是，他是写在参数左侧的。如（ @ApiParam(name="username",value="用户名")String username）
@ApiModel： 用于类，表示对类进行说明，用于参数用实体类接收
@ApiModelProperty： 用于方法，字段，表示对model属性的说明或者数据操作更改
@ApiImplicitParam： 用于方法，表示单独的请求参数
@ApiImplicitParams： 用于方法，包含多个 @ApiImplicitParam
@ApiResponse： 用于方法，描述单个出参信息
@ApiResponses： 用于方法，包含多个@ApiResponse
@ApiError： 用于方法，接口错误所返回的信息
挂张图：
开始配置
1. 导入依赖
配置基于Spring Boot 2.2.1
<properties>
<swagger.version>2.9.2</swagger.version>
</properties>
...
<!-- swagger2 来自RuoYi -->
<dependency>
<groupId>io.springfox</groupId>
<artifactId>springfox-swagger2</artifactId>
<version>${swagger.version}</version>
<exclusions>
<exclusion>
<groupId>io.swagger</groupId>
<artifactId>swagger-annotations</artifactId>
</exclusion>
<exclusion>
<groupId>io.swagger</groupId>
<artifactId>swagger-models</artifactId>
</exclusion>
</exclusions>
</dependency>
<!--防止进入swagger页面报类型转换错误，排除2.9.2中的引用，手动增加1.5.21版本-->
<dependency>
<groupId>io.swagger</groupId>
<artifactId>swagger-annotations</artifactId>
<version>1.5.21</version>
</dependency>
<dependency>
<groupId>io.swagger</groupId>
<artifactId>swagger-models</artifactId>
<version>1.5.21</version>
</dependency>
<!-- swagger2-UI-->
<dependency>
<groupId>io.springfox</groupId>
<artifactId>springfox-swagger-ui</artifactId>
<version>${swagger.version}</version>
</dependency>
2. 写配置文件
application.properties
# application.properties中控制是否开启swagger
swagger.enabled=true
SwaggerConfig.java
@EnableSwagger2
@Configuration
public class SwaggerConfig {
/** 是否开启swagger */
@Value("${swagger.enabled}")
private boolean enabled;
/**
* 创建API
*/
@Bean
public Docket createRestApi()
{
return new Docket(DocumentationType.SWAGGER_2)
// 是否启用Swagger
.enable(enabled)
// 用来创建该API的基本信息，展示在文档的页面中（自定义展示的信息）
.apiInfo(apiInfo())
// 设置哪些接口暴露给Swagger展示
.select()
// 扫描所有有注解的api，用这种方式更灵活
.apis(RequestHandlerSelectors.withMethodAnnotation(ApiOperation.class))
// 扫描指定包中的swagger注解
//.apis(RequestHandlerSelectors.basePackage("com.ruoyi.project.tool.swagger"))
// 扫描所有 .apis(RequestHandlerSelectors.any())
.paths(PathSelectors.any())
.build();
}
/**
* 添加摘要信息
*/
private ApiInfo apiInfo()
{
// 用ApiInfoBuilder进行定制
return new ApiInfoBuilder()
// 设置标题
.title("标题：XX管理系统_接口文档")
// 描述
.description("描述：用于管理集团旗下公司的人员信息,具体包括XXX,XXX模块...")
// 作者信息
.contact(new Contact("xxx项目", null, null))
// 版本
.version("版本号:" + "v1.1.0")
.build();
}
}
3. 编写测试类，并添加相关API注解
Student.java
/**
* @author liuyiyuan
*/
@ApiModel(description="学生数据类型")
public class Student {
@ApiModelProperty(value = "学生姓名", name="name",
dataType="String",
required=true,
position=3, //排序，越小越靠前
example="tom")
private String name;
@ApiModelProperty(value = "学生班级名", name="className",
required=true,
dataType="String",
position=5,
example="tom")
private String className;
@ApiModelProperty(value = "学生年龄", name="age",
required=true,
dataType="Integer",
position=2,
example="15")
private Integer age;
public Student(String name, String className, Integer age) {
this.name = name;
this.className = className;
this.age = age;
}
//getter、setter
}
Controller
/**
* @author liuyiyuan
*/
@Api(value = "学生管理模块API", tags = "学生管理")
//@ApiIgnore //忽略本类中的api
@RestController
@RequestMapping("/stu")
public class StudentController {
@ApiResponse(
code = 200,
message = "成功",
response = ArrayList.class
)
@ApiOperation(value = "获取列表",
tags = {"tag2..", "分为多个标签"},
httpMethod = "GET")
@GetMapping("/stus")
public List<Student> listStudent() {
List<Student> ss = new ArrayList<>();
ss.add(new Student("aaa", "1班", 13));
ss.add(new Student("bbb", "2班", 15));
ss.add(new Student("ccc", "3班", 11));
ss.add(new Student("ddd", "4班", 16));
return ss;
}
@ApiResponse(
code = 200,
message = "成功",
response = Student.class
)
@ApiOperation(value = "获取一个对象",
tags = {"tag1..", "分为多个标签"},
nickname = "昵称",
httpMethod = "GET")
@GetMapping("/stu")
public Student getStudent(@ApiParam(name = "idx", value = "要获取学生数据的索引值", defaultValue = "1") @RequestParam("idx") Integer index) {
List<Student> ss = new ArrayList<>();
ss.add(new Student("aaa", "1班", 13));
ss.add(new Student("bbb", "2班", 15));
ss.add(new Student("ccc", "3班", 11));
ss.add(new Student("ddd", "4班", 16));
return ss.get(index);
}
@ApiImplicitParam(
name = "student",
value = "要插入的新数据",
required = true,
dataType = "Student",
paramType = "body"
)
@ApiOperation(value = "插入新值")
@PostMapping("/stus")
public Student post(@RequestBody Student student) {
System.out.println("插入新值...===> " + student);
return student;
}
@ApiOperation(value = "修改")
@ApiImplicitParam(
name = "student",
value = "要修改的新学生数据",
required = true,
paramType = "body",
dataType = "Student"
)
@PutMapping("/stus")
public Student put(@RequestBody Student student) {
System.out.println("修改新值...===> " + student);
return student;
}
@ApiOperation(value = "删除",
httpMethod = "DELETE")
@DeleteMapping("/stus/{idx}")
@ApiImplicitParam(name = "idx", value = "删除对象的索引值", paramType = "path")
public Student del(@PathVariable("idx") Integer index) {
List<Student> ss = new ArrayList<>();
ss.add(new Student("aaa", "1班", 13));
ss.add(new Student("bbb", "2班", 15));
ss.add(new Student("ccc", "3班", 11));
ss.add(new Student("ddd", "4班", 16));
System.out.println("删除值==> " + ss.get(index));
return ss.get(index);
}
}