Swagger 的 基本使用方式

1、不使用JOSN格式时的

    @ApiOperation(value = "发票记录（分页）", notes = "发票记录（分页）")
    @ApiImplicitParams({
            @ApiImplicitParam(paramType = "query", name = "id", value = "人员id", dataType = "Long"),
            @ApiImplicitParam(paramType = "query", name = "enable", value = "是否启用，true或者false", dataType = "Boolean"),
    })
    @ApiResponses({
            @ApiResponse(code = 200,message = "OK",response = ReceptionInvoiceInfoDto.class),
    })
    @GetMapping("/page/invoiceInfoDto")
    public Result pageReceptionInvoiceInfoDto(ReceptionInvoiceInfoDto receptionInvoiceInfoDto, Pageable pageable, String uid){
        return Result.success(receptionInvoiceService.pageReceptionInvoiceInfoDto(receptionInvoiceInfoDto, pageable, uid));
    }

其中

@ApiImplicitParams 中的是 path 或者 query 类型的参数

@ApiResponses 则是指定返回的参数类（必须通过 @ApiModel 和 @ApiModelProperty 两个注解搭配，才能给 swagger 上的 Model 添加说明信息）

2、使用JSON格式的

    @ApiOperation(value = "提交接待预约申请", notes = "提交接待预约申请")
    @ApiImplicitParams({
    })
    @Transactional(rollbackFor = {BusinessException.class, Error.class}, propagation = Propagation.REQUIRED)
    @PostMapping(value = "/submit/appointment")
    public Result submitAppointment(@NotNull @RequestBody SubmitAppointmentDto submitAppointmentDto) {
        Long receptionAppointmentId = receptionAppointmentService.submitAppointment(submitAppointmentDto);
        return Result.success(receptionAppointmentId);
    }

使用 JSON 接收前端传参时，就不需要再在 @ApiImplicitParams 里写那一大堆东西了，通过给 SubmitAppointmentDto 添加 @ApiModel 和 @ApiModelProperty 注解，swagger会自动生成。

3、 @ApiModel 和 @ApiModelProperty

@ApiModel：加在类上

@ApiModelProperty ：加在成员变量上

@ApiModel(value = "接待预约申请信息")
@Data
public class SubmitAppointmentDto {

    /**
     * 微信用户的openid tb_reception_appointment.openid
     */
    @ApiModelProperty(value = "微信用户的openid", required = true)
    private String openid;

    /**
     * 参观单位名称 tb_reception_appointment.unit_id
     */
    @ApiModelProperty(value = "基地id", hidden = true)
    private Long unitId;


    /**
     * 预约参观开始时间 tb_reception_appointment.start_date
     */
    @DateTimeFormat(pattern="yyyy-MM-dd HH:mm:ss")
    @JsonFormat(
            pattern = "yyyy-MM-dd HH:mm:ss",
            timezone = "GMT+8"
    )
    @ApiModelProperty(value = "预约参观开始时间，时间戳格式", dataType = "Long", required = true)
    private Date startDate;


    /**
     * 是否是工作日 默认是工作日 tb_reception_appointment.is_workday
     */
    @ApiModelProperty(value = "是否是工作日 默认是工作日", required = true)
    private Boolean isWorkday;

    /**
     * 除领导以外的同行人信息 tb_reception_appointment_info
     */
    @ApiModelProperty(value = "是否是工作日 默认是工作日", required = true)
    private List<ReceptionPeerInfoDto> peerList;

    /**
     * 需要参观的场景项目 ReceptionSceneProject 的 id
     */
    @ApiModelProperty(value = "需要参观的场景项目")
    private List<ProjectIdAndCount> sceneProjectIdAndCount;



}

4、最终效果：

（1）@ApiResponses 的效果图：

（2）使用 JSON 接收参数时的效果图：