SpringBoot下使用Swagger2开发API文档
使用基础在前后端分离开发的后端代码简单案例上进行
下面是完整代码案例
1.依赖导入
<!--web启动器-->
<dependency>
<groupId>org.springframework.boot</groupId>
<artifactId>spring-boot-starter-web</artifactId>
</dependency>
<!--数据库连接-->
<dependency>
<groupId>mysql</groupId>
<artifactId>mysql-connector-java</artifactId>
<version>5.1.47</version>
</dependency>
<!--mybatis-plus启动器-->
<dependency>
<groupId>com.baomidou</groupId>
<artifactId>mybatis-plus-boot-starter</artifactId>
<version>3.4.0</version>
</dependency>
<!--代码生成器-->
<dependency>
<groupId>com.baomidou</groupId>
<artifactId>mybatis-plus-generator</artifactId>
<version>3.4.0</version>
</dependency>
<dependency>
<groupId>org.apache.velocity</groupId>
<artifactId>velocity-engine-core</artifactId>
<version>2.2</version>
</dependency>
<!-- swagger2 -->
<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>
<!--解决Illegal DefaultValue null for parameter type integer-->
<!--主要是驼峰命名不规范问题-->
<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>
<dependency>
<groupId>org.projectlombok</groupId>
<artifactId>lombok</artifactId>
<optional>true</optional>
</dependency>
2.配置类
@Configuration
@EnableSwagger2 //开启注解
public class SwaggerConfig {
//需要向Spring容器中注入一个Bean,会根据Swagger注解生成API文档
@Bean
public Docket buildDocket(){
return new Docket(DocumentationType.SWAGGER_2)//使用的类型是SWAGGER_2类型
.apiInfo(buildApiInfo())
.select() //进行选择生成
// .apis(RequestHandlerSelectors.any())//指定所有类都生成API com.example.stu.controller
.apis(RequestHandlerSelectors.basePackage("com.example.stu.controller"))//指定哪些包下的类生成API
// .apis(RequestHandlerSelectors.withClassAnnotation(Api.class))//指定标记了特定注解的类进行生成
.paths(PathSelectors.any())
.build();
}
//设置文档的基本信息
private ApiInfo buildApiInfo() {
return new ApiInfoBuilder()
.title("文档标题*******")
.description("文档描述****")
.version("版本****")
.termsOfServiceUrl("服务支持网址")
.license("许可协议")
.licenseUrl("许可协议网址")
.contact(new Contact("作者姓名","作者博客地址","email地址"))
.build();
}
}
3. application.properties
# 微服务命名
spring.application.name=stu-service
#端口声明
server.port=8089
#数据库配置
spring.datasource.url=jdbc:mysql://localhost:3306/temporary?useUnicode=true&useSSL=false&characterEncoding=utf8
spring.datasource.username=root
spring.datasource.password=12345
spring.datasource.driver-class-name=com.mysql.jdbc.Driver
#logging.level.root=debug
4.实体类
@Data
@EqualsAndHashCode(callSuper = false)
@ApiModel(value="Student对象", description="")
public class Student implements Serializable {
private static final long serialVersionUID = 1L;
@ApiModelProperty(name = "id",value = "编号",example = "1")
@TableId(type = IdType.AUTO) //声明id 为自增长
private Integer id;
@ApiModelProperty(name = "name",value = "学生姓名",example = "张三",required = true)
private String name;
@ApiModelProperty(name = "sSex",value = "学生性别",example = "男",required = true)
@TableField("s_sex")//用于字段匹配
private String sSex;
}
5.返回前端数据封装类
//用于返回数据的封装
@Data
public class R {
private Integer code;
private Boolean status;
private Map<String,Object> data =new HashMap<>();
private String message;
//私有构造方法
private R(){}
//链式编程
public static R ok(){
R r = new R();
r.setStatus(true);
r.setCode(200);
return r;
}
public static R error(String message,Integer code){
R r =new R();
r.setStatus(false);
r.setCode(code);
r.setMessage(message);
return r;
}
//数据封装
public R put(String key,Object value){
this.data.put(key,value);
return this;
}
}
6.mapper及service
StudentMapper
public interface StudentMapper extends BaseMapper<Student> {
}
IStudentService
public interface IStudentService extends IService<Student> {
Page pageList(StudentVo studentVo);
}
StudentServiceImpl
@Service
public class StudentServiceImpl extends ServiceImpl<StudentMapper, Student> implements IStudentService {
@Override
public Page pageList(StudentVo studentVo) {
QueryWrapper queryWrapper = new QueryWrapper();
if(!StringUtils.isEmpty(studentVo.getName())){
queryWrapper.eq("name",studentVo.getName());
}
if (!StringUtils.isEmpty(studentVo.getId())){
queryWrapper.eq("id",studentVo.getId());
}
if (!StringUtils.isEmpty(studentVo.getSSex())){
queryWrapper.eq("s_sex",studentVo.getSSex());
}
if (studentVo.getMaxId()!=null){
queryWrapper.lt("id",studentVo.getMaxId());
}
if (studentVo.getMinId()!=null){
queryWrapper.gt("id",studentVo.getMinId());
}
queryWrapper.orderByAsc("id");
Page page = new Page();
page.setCurrent(studentVo.getCurrentPage());
page.setSize(studentVo.getPageSize());
baseMapper.selectPage(page,queryWrapper);
System.out.println(page.getTotal());
return page;
}
}
7. vo
StudentVo
主要用来与前端数据交互,涉及分页等信息
@Data
@ApiModel
public class StudentVo {
@ApiModelProperty(name = "id",example = "1")
private Integer id;
private String name;
private String sSex;
@ApiModelProperty(name = "currentPage",value = "当前页",example = "1",required = true)
private Integer currentPage;
@ApiModelProperty(name = "pageSize",value = "每页显示条数",example = "3",required = true)
private Integer pageSize;
private Integer maxId;
private Integer minId;
}
8.controller
@Api(tags = "完成了student的CRUD功能")//tags对该类进行功能说明
@RestController
@RequestMapping("/stu/student")
public class StudentController {
@Autowired
private IStudentService studentService;
//RestFul风格
//获取所有
@ApiOperation("完成student列表的获取")//说明是一个操作项
@GetMapping
public R list(){
return R.ok().put("data",studentService.list());
}
@ApiOperation("完成student的分页查询")//说明是一个操作项
//条件查询
@PostMapping
public R pageList(@ApiParam(name = "studentVo",value = "查询条件")@RequestBody StudentVo studentVo){
Page pageList = studentService.pageList(studentVo);
return R.ok().put("total",pageList.getTotal()).put("data",pageList.getRecords());
}
//新增
@ApiOperation("完成student新增操作")
@PostMapping("/save")
public R save(@ApiParam(name = "student",value = "要新增的student")@RequestBody Student student){
studentService.save(student);
return R.ok();
}
//修改 先根据id获取结果返回给前端,前端在已有的基础上进行修改
@ApiOperation("完成student修改前的查询")
@GetMapping("/{id}")
public R getById(@ApiParam(name = "id",value = "要修改对象的id",required = true)@PathVariable("id") Integer id){
Student byId = studentService.getById(id);
return R.ok().put("data",byId);
}
// 提交后的修改操作
@ApiOperation("完成student修改操作")
@PutMapping()
public R update(@ApiParam(name = "要修改的student",required = true)@RequestBody Student student){
studentService.updateById(student);
return R.ok();
}
//删除
@ApiOperation("完成student的删除操作")
@DeleteMapping("/{id}")
public R deleteById(@ApiParam(name = "id",required = true,value = "要删除的学生id")@PathVariable("id") Integer id){
studentService.removeById(id);
return R.ok();
}
//删除
@ApiOperation("完成student的批量删除操作")
@DeleteMapping
public R deleteByIds(@ApiParam("要删除的student id")@RequestParam List<Long> ids){
studentService.removeByIds(ids);
return R.ok();
}
}
9.DemoApplication
@SpringBootApplication
@MapperScan("com.example.stu.mapper")
public class DemoApplication {
public static void main(String[] args) {
SpringApplication.run(DemoApplication.class, args);
}
}
10.最终显示结果
显示网址:http://localhost:8089/swagger-ui.html