注解使用文档

由于swagger针对我们代码工程存在不匹配的情况，针对注解决定使用我们自己研发的注解，该注解满足以下接口需求，其中我们自己定义的注解以及注解属性名与swagger大致保持一致，以这样的方式解决自动生成API文档

包含注解：@Api（类注解），@ApiOperation（方法注解），@ApiParams（方法注解，参数），@ApiParam（参数注解）

注解属性说明：

@Api

属性名	属性类型	属性说明
module	ApiModuleEnum(枚举)	所属模块
subModuleName	String	子模块名
value	String	描述
type	ApiTypeEnum（枚举）	接口类型
opportunity	String	事件类填写，触发时间

@ApiOperation

属性名	属性类型	属性说明
name	String	方法中文名称
value	String	方法描述
scenes	String	应用场景
createDate	String	开发时间

@ApiParams

属性名	属性类型	属性说明
params	ApiParam[]（注解）	参数

@ApiParam

属性名	属性类型	属性说明
name	String	参数名
value	String	参数说明
defaultValue	String	参数默认值
allowableValues	String	参数允许的值
required	Boolean	是否必传，true必传，false非必传
apiParamLocation	ApiParamLocationEnum（枚举）	参数位置（path、query）
classType	Class	参数返回值类型

备注：

枚举类：

ApiModuleEnum

取值	说明
global	全局模块
collaboration	协同模块
form	表单模块
doc	知识管理模块
edoc	公文模块
plan	计划模块
meeting	会议模块
bulletin	公告模块
news	新闻模块
bbs	讨论模块
inquiry	调查模块
calendar	日程模块
mail	邮件模块
organization	组织模型模块
taskManage	任务管理模块
attendance	签到模块
cmp	cmp模块
cap4Form	cap4模块
message	消息模块
office	综合办公模块
portal	门户模块
project	项目管理模块
supervision	督办模块
xiaoz	小智模块
zhifei	致飞模块
ai	AI智能插件模块

ApiTypeEnum

取值	说明
DYNAMIC	动态接口
REST	REST接口
EVENT	event事件

ApiParamLocationEnum

取值	说明
PATH	path路径
QUERY	query参数
BODY	body参数针对于post请求

示例

Event示例

@Api(module = ApiModuleEnum.meeting,value = "会议待办生成监听事件",type = ApiTypeEnum.EVENT)
public class MeetingAffairsAssignedEvent extends Event{
@ApiOperation(name = "获取Affairs",value = "获取Affairs",scenes = "事件get/set方法")
public List<CtpAffair> getAffairs() {
 return affairs;
}
@ApiOperation(name = "设置Affairs",value = "设置Affairs",scenes = "事件get/set方法")
public void setAffairs(@ApiParam(name = "affairs",value = "affairs",required = true,classType = List.class) List<CtpAffair> affairs) {
 this.affairs = affairs;
}
}

Rest示例

@ApiOperation(name = "获取人员的头像",value = "获取人员的头像",scenes = "获取人员的头像")
public Response getAvatar(@PathParam("memberId") @ApiParam(name = "memberId",value = "人员id",required = true,classType = Long.class) Long memberId,
        @QueryParam("showType")@DefaultValue("small") @ApiParam(name = "showType",value = "是否显示为缩略图，默认显示：small",required = true,classType = String.class) String showType,
        @QueryParam("maxWidth")@DefaultValue("400") @ApiParam(name = "maxWidth",value = "缩略图最大宽度，默认为（400）",required = true,classType = int.class) int maxWidth) throws Exception {
}

rest接口最新规范：https://open.seeyoncloud.com/v5dev/39/76/

Dynamic动态接口示例

@Since("8.1")
@Api(module = ApiModuleEnum.meeting,value = "会议-动态埋点",type = ApiTypeEnum.DYNAMIC)
public abstract class MeetingAjaxManagerImplDynamicApi implements MeetingDynamicApi {
   /**
      动态埋点：MeetingAjaxManagerImpl中findMeetingList方法结束时，执行其他客开动作
      场景：专题会议和原会议共用了会议的列表，需要重写列表里面的数据
      @param params 参数
     /
   @Since("8.1")
   @ApiOperation(name = "查找会议列表后",value = "MeetingAjaxManagerImpl中findMeetingList方法结束时，执行其他客开动作",scenes = "专题会议和原会议共用了会议的列表，需要重写列表里面的数据",createDate = "2021/7/5")
   public void afterFindMeetingList(@ApiParam(name = "params", value = "DynamicMeetingListParam", required = true, classType = DynamicMeetingListParam.class) DynamicMeetingListParam params){};
}