Swagger学习笔记

Swagger

一、开发模式

1. 前后端：
   前端：客户端
   后端：服务器端

2. 前后端分离：服务器与客户端不在一个应用中

3. 开发时，前端需要知道穿什么参数后端，后端需要知道相应什么数据给前端—>需要并行开发—>接口文档

4. 联调：开发完成后需要联合调试

二、接口文档

1. 概述

接口文档：前后端分离开发中的一种约束文档，规定开发人员按照文档进行开发

2. 编写

1. 需要指定请求URL、请求方式、请求参数、响应结果等数据
2. 一个应用有很多接口，造成编写接口文档是很耗时的，不能把大把精力放在此上
3. 需要动态生成接扣文档的技术—>Swagger

三、应用

• 因为依赖冲突的问题，把springboot版本降到了2.2.9.RELEASE
• swagger：2.9.2

1. 概述

能够快速生成在线图形化的接口文档，帮我们实现前后端分离开发

2. 快速入门

1. 导入依赖

<!-- 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>

2. 开启Swagger

@Configuration
@EnableSwagger2
public class SwaggerConfig {
}

3. 编写接口

@RestController
@RequestMapping("/employee")
public class EmployeeController {

    @GetMapping("/list")
    public ResultVO findAll(){
        List<Employee> emps = new ArrayList<>();
        emps.add(new Employee());
        emps.add(new Employee());
        emps.add(new Employee());
        return ResultVO.ok("员工列表查询成功", emps);
    }

}

4. 运行
   http://localhost:8002/swagger-ui.html
   

3. 核心配置

核心配置对象：Docket

1. ApiInfo

@Configuration
@EnableSwagger2
public class SwaggerConfig {

    @Bean
    public Docket docket(){
        Contact contact = new Contact("swagger666", "https://swagger.io/", "swagger666@163.com");
        return new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(
                        new ApiInfo(
                                "title",
                                "description",
                                "1.0",
                                "http://www.baidu.com",
                                contact,
                                "license",
                                "http://www.javahhhlicense.com",
                                new ArrayList<>()
                        )
                );
    }

}

2. 组名，限定接口规则
   
   

4. 接口注解

1. @Api：标记在控制器上，用于对整个模块功能进行描述
2. @APIOperation：标记在接口上，用于对接口功能进行描述
3. @ApiImplicit/@ApiImplicitParams：标记在目标接口【handler】上，用于对入参参数进行描述

package com.qf.java2107.springboot.demo03.controller;

import com.qf.java2107.springboot.demo03.entity.ResultVO;
import com.qf.java2107.springboot.demo03.pojo.Employee;
import io.swagger.annotations.Api;
import io.swagger.annotations.ApiImplicitParam;
import io.swagger.annotations.ApiOperation;
import org.springframework.web.bind.annotation.*;

import java.util.ArrayList;
import java.util.List;

/**
 * @author ghy
 * @version 1.0
 * @date 2022-01-12
 **/
@RestController
@RequestMapping("/employee")
@Api(tags = "员工功能1.0", value = "提供员工模块的具体功能")
public class EmployeeController {

    @ApiOperation(value = "员工查询", notes = "查询所有员工数据")
    @GetMapping("/list")
    public ResultVO findAll(){
        List<Employee> emps = new ArrayList<>();
        emps.add(new Employee());
        emps.add(new Employee());
        emps.add(new Employee());
        return ResultVO.ok("员工列表查询成功", emps);
    }

    @ApiOperation(value = "员工新增", notes = "增加一个新员工数据")
    //dataType: 参数数据类型   example:示例值
    @ApiImplicitParam(name = "employee", value = "员工实体", dataType = "Employee", example="{empName:\"jack\", birthday:\"1992-12-12\"}")
    @PostMapping("/save")
    public ResultVO save(@RequestBody Employee employee){
        return ResultVO.ok("员工新增成功");
    }

    @ApiOperation(value = "员工删除", notes = "根据ID删除员工数据")
    @ApiImplicitParam(name = "id", value = "员工ID", dataType = "int", example="100")
    @DeleteMapping("/delete/{id}")
    public ResultVO deleteById(@PathVariable("id") Integer id){
        return ResultVO.ok("员工删除成功", id);
    }

    @ApiOperation(value = "员工修改", notes = "修改一个员工数据")
    @PutMapping("/modify")
    public ResultVO modify(@RequestBody Employee employee){
        return ResultVO.ok("员工修改成功");
    }

    @GetMapping("/findOne")
    @ApiOperation(value = "员工查询", notes = "根据ID查询员工数据")
    @ApiImplicitParam(name = "id", value = "员工ID", dataType = "int", example="111")
    public ResultVO modify(@RequestParam("id") Integer id){
        return ResultVO.ok("员工查询成功", id);
    }

}

5 实体注解

1. ApiModel：标记类上：描述实体
2. ApiModelProperty：标记属性：描述属性

@Data
@NoArgsConstructor
@AllArgsConstructor
@TableName("t_employee")
@ApiModel(value = "员工", description = "员工实体，对应数据库表t_employee")
public class Employee {

    @ApiModelProperty(name = "emp_name", notes = "员工姓名", dataType = "String", example = "李三")
    private String empName;

    @DateTimeFormat(pattern = "yyyy-MM-dd")
    @JsonFormat(pattern = "yyyy-MM-dd")
    @ApiModelProperty(name = "生日", notes = "员工生日", dataType = "Date", example = "1999-11-11")
    private Date birthday;
    
    //............
}