接口设计与开发规范

设计JAVA开发的RESTFUL接口规范，需要满足以下要求：

• controller类指定@Api注解

• 指定@Api的value属性、指定@Api的tags属性

• controller类接口对应方法指定@ApiOperation注解

• 指定@ApiOperation的value属性

• 接口命名请以listing,delete, add等英文字母开头，目前定义的英文开头参考如下：

新增接口：addXxx
分页接口：pagingXxx
列表接口：listingXxx\queryXxx
树接口：plantXxx
更新接口：updateXxx
获取详情接口：detailsXxx\getXxx
删除接口：deleteXxx
激活接口：activateXxx
冻结接口：freezeXxx
下载文件：downloadFile 
判断文件存在：existsFile
复制文件：copyFile
上传文件：uploadFile
文件压缩：compressFile
文件解压：decompressFile
同步文件：syncFile
识别文件：recogniseFile
获取文件详情：detailsFile

• 接口命名规范5到16位以小写开头的大小写英文字母
• @RequestMapping指定method属性
• 接口的请求参数，若是model对象的，请指定好@ApiModelProperty及它的简要描述属性value，若不是model的，请指定好@ApiImplicitParams及它@ApiImplicitParam中的name及value简要描述属性。例如：

@ApiImplicitParams(value = {
            @ApiImplicitParam(name = "subjectId", value = "学科ID")
    })
public ResponseEntity<?> getKnowledgeChart(@RequestParam String subjectId)
或者  
class school{
    @ApiModelProperty(value="用户名",name="userName")  
    private String userName;
}

• Api的请求url路径要求http://ip:port/微服务名称/{多级模块}/{动宾结构的方法名称}，例如：http://192.168.0.0:18090/微服务名称/user/getUser，注意：
  • 多级模块：名称请使用名词。例如：/management/public/
  • 多级模块：业务型微服务按多级菜单去分层划分模块，例如：/综合管理/公共资源/。功能型微服务按功能区分模块，例如：/文件/。
• url接口命名不要出现数字