给swagger的接口添加描述

swgger非常便于前后端分离开发，通过给swagger添加描述就可以实现前后端共同的开发接口，以下介绍如何给swagger的接口添加描述。

一.创建实体，并在实体和属性上使用@ApiModel()、@ApiModelProperty()注解。

注解的具体文档请参考https://blog.csdn.net/dejunyang/article/details/89527348

1.1 工作者实体

//工作者实体
import com.alibaba.fastjson.annotation.JSONField;
import com.baomidou.mybatisplus.annotations.TableField;
import com.baomidou.mybatisplus.annotations.TableId;
import com.baomidou.mybatisplus.annotations.TableName;
import com.baomidou.mybatisplus.enums.IdType;
import io.swagger.annotations.ApiModel;
import io.swagger.annotations.ApiModelProperty;
import lombok.Data;
import javax.validation.constraints.NotEmpty;
import java.util.Date;
import java.util.List;

@Data
@TableName("XXW_WORKER_T")
@ApiModel("工作者实体")
public class XxwWorkerT extends FieldFillBean {
    /**
     * 主键
     */
    @TableId(value = "XXW_WORKER_ID", type = IdType.UUID)
    @ApiModelProperty("主键id")
    private String xxwWorkerId;
    /**
     * 姓名
     */
    @TableField("NAME")
    @NotEmpty(
            message = "姓名不能为空"
    )
    @ApiModelProperty("姓名")
    private String name;
    /**
     * 年龄
     */
    @TableField("AGE")
    @ApiModelProperty("年龄")
    private Integer age;
    /**
     * 出生日期
     */
    @TableField("BIRTHDAY")
    @JSONField(format = "yyyy-MM-dd")
    @ApiModelProperty("出生日期")
    private Date birthday;

    @ApiModelProperty("代码表")
    private DemoTable demoTable;

    @ApiModelProperty("用户表吧")
    private List userBas;
}

1.2 代码表实体

//代码表实体
import io.swagger.annotations.ApiModel;
import io.swagger.annotations.ApiModelProperty;
import lombok.Data;
@Data
@ApiModel("demo表")
public class DemoTable {
    @ApiModelProperty("表名称")
    private String tableName;

    @ApiModelProperty("表代码")
    private String tableCode;
}

1.3 用户吧实体

import io.swagger.annotations.ApiModel;
import io.swagger.annotations.ApiModelProperty;
import lombok.Data;

@Data
@ApiModel("userBa表")
public class UserBa {
    @ApiModelProperty("用户名称")
    private String userBaName;

    @ApiModelProperty("用户代码")
    private String userBaCode;
}

二、controller使用resultful风格请求

2.1 post请求

2.1.1 controller实现方式

  /**
     * 增加一个新的工作者
     */
    @ApiOperation("增加一名新的工作者")
    @RequestMapping(
            value = {"/addOneWorker"},
            method = {RequestMethod.POST}
    )
    public ResponseData addOneWorker(@Valid @RequestBody XxwWorkerT xxwWorkerT){
            this.xxwWorkerTService.addOneWorker(xxwWorkerT); //新增接口
            return SUCCESS_TIP;
    }

2.1.2 效果演示

2.2 get请求

2.2.1 controller实现方式

 /**
     * 条件分页查询工作者名单
     */
    @GetMapping(value = "/selectWorkerListByPage")
    @ApiImplicitParams({
            @ApiImplicitParam(name = "pageSize", value = "每页显示数量", required = false, dataType = "Integer", example = "10", paramType = "query"),
            @ApiImplicitParam(name = "pageNo", value = "第几页，从1开始", required = false, dataType = "Integer", example = "1", paramType = "query"),
            @ApiImplicitParam(name = "name", value = "姓名", required = false, dataType = "String", paramType = "query"),
            @ApiImplicitParam(name = "age", value = "年龄", required = false, dataType = "Integer", paramType = "query"),
            @ApiImplicitParam(name = "birthday", value = "出生日期", required = false, dataType = "String", paramType = "query")
    })
    @ResponseBody
    @ApiOperation(value = "条件分页查询工作者名单", notes = "条件分页查询工作者名单")
    public RawResponseQi selectWorkerListByPage(
            @RequestParam(required = false) String name,
            @RequestParam(required = false) Integer age,
            @RequestParam(required = false) String birthday) {
        return xxwWorkerTService.selectWorkerListByPage(name, age, birthday);
    }

2.2.2 效果演示

2.3 put请求

2.3.1 controller实现方式

 /**
     * 更新工作者信息
     */
    @PutMapping(value = "/updateOneWorker")
    @ApiOperation(value = "修改一名工作者信息", notes = "修改一名工作者信息")
    public ResponseData updateOneWorker(@Valid @RequestBody XxwWorkerT xxwWorkerT){
        this.xxwWorkerTService.updateOneWorker(xxwWorkerT);
        return SUCCESS_TIP;
    }

2.3.2 效果演示

2.4 delete请求

2.4.1 delete实现方式

@DeleteMapping(value = "/deleteOneWorker")
    @ApiOperation(value = "删除一名新的工作者", notes = "删除一名新的工作者")
    public ResponseData deleteOneWorker(@RequestParam(value = "id",required = true) String id){
        this.xxwWorkerTService.deleteOneWorker(id);
        return SUCCESS_TIP;
    }

2.4.2 效果演示