个人周记丨2019-12-01 swagger注解，优雅的使用ApiImplicitParams生成复杂对象

概述

在使用swagger编写文档时，我们可能需要接收一个复杂对象，这时我们便会使用ApiImplicitParams注解来完成我们的需求。

需求

现在我要接受一个医院机构对象，如何使用ApiImplicitParams注解来优雅的展示呢。

实现

• 1.项目搭建与配置
  此处略，请参考网上资料
• 2.dbo医院机构对象
  dbo对象可以使用mybatis-plus代码生成器完成
  dbo对象需要为其加上ApiModel注解，并使用value方法赋值

@ApiModel(value = "MedicalInstitution",description = "医院机构")
@TableName("MEDICAL_INSTITUTION")
public class MedicalInstitution extends Model<MedicalInstitution> {

    private static final long serialVersionUID = 1L;

    @TableId(value = "MEDI_INST_CODE", type = IdType.UUID)
    @ApiModelProperty("机构码")
    private String mediInstCode;

    @ApiModelProperty("机构名称")
    private String mediInstName;

    @ApiModelProperty("机构的库名")
    private String dbName;

    @ApiModelProperty("历史机构号")
    @TableField(exist = false)
    private String oldMediInstCode;

    public String getOldMediInstCode() {
        return oldMediInstCode;
    }

    public void setOldMediInstCode(String oldMediInstCode) {
        this.oldMediInstCode = oldMediInstCode;
    }

    public String getDbName() {
        return dbName;
    }

    public void setDbName(String dbName) {
        this.dbName = dbName;
    }

    public String getMediInstCode() {
        return mediInstCode;
    }

    public void setMediInstCode(String mediInstCode) {
        this.mediInstCode = mediInstCode;
    }

    public String getMediInstName() {
        return mediInstName;
    }

    public void setMediInstName(String mediInstName) {
        this.mediInstName = mediInstName;
    }

    @Override
    protected Serializable pkVal() {
        return this.mediInstCode;
    }

    @Override
    public String toString() {
        return "MedicalInstitution{" +
        "mediInstCode=" + mediInstCode +
        ", mediInstName=" + mediInstName +
        "}";
    }
}

• 3.在接口上使用机构对象
  使用ApiImplicitParams注解
  并在该注解体内添加成员ApiImplicitParam，使用dataType方法，为该方法赋值，值为dbo机构对象ApiModel注解value所对应的值（ApiImplicitParams注解体内可以使用多个ApiImplicitParam，如果只有一个ApiImplicitParam，建议直接使用ApiImplicitParam）。例如本文赋值的为MedicalInstitution

@Controller
@RequestMapping("hospital")
@Api(value = "医院模块",description = "医院管理相关的接口")
public class HospitalController {

    @Autowired
    MedicalInstitutionService medicalInstitutionService;


    @ApiOperation("新增医院")
    @RequestMapping(value = "add",method = RequestMethod.POST)
    @ResponseBody
    @ApiImplicitParams(
            @ApiImplicitParam(dataType = "MedicalInstitution",name = "medicalInstitution")
    )
    public JsonRet add(@RequestBody MedicalInstitution medicalInstitution){

        MedicalInstitution dbData = medicalInstitutionService.getById(medicalInstitution.getMediInstCode());
        if(dbData != null){
            return JsonRet.buildFailRet("该机构号已经存在");
        }
        medicalInstitutionService.save(medicalInstitution);
        return JsonRet.buildSuccRet(null);
    }
}

总结

最后看看效果，这就是ApiImplicitParams的优雅使用啦。