服务端 - 接口规范与文档 - 《西安交通信息Java开发平台V1》

规范原则
请求方法
请求规则
响应基本格式
接口文档

规范原则

接口返回数据即显示，前端仅做渲染逻辑处理；
前端关注交互、渲染逻辑，尽量避免业务逻辑处理的出现；
请求响应传输数据格式为JSON，JSON数据尽量简单轻量；

请求方法

框架中前端请求后端只允许使用GET和POST，框架内置模块全部使用POST方法请求。

请求规则

1. 验证appId

appId表示应用标识，可以用来区分客户端身份或者类型，例如WinForm客户端使用appId=winApp，安卓客户端使用appId=androidApp，请客户端进行请求时，服务端可以根据appId来确定是安卓客户端还是WinForm客户端，同时也可以判断客户端传递的appId是否正确，对于非法客户端的请求就可以直接拦截。

appId参数在客户端请求时在http请求头中添加，键:appId，值:系统分配的appId。

2. 验证timestamp

时间戳本意是指格林威治时间1970年01月01日00时00分00秒(北京时间1970年01月01日08时00分00秒)起至现在的总秒数。

timestamp表示格林威治时间1970年01月01日00时00分00秒(北京时间1970年01月01日08时00分00秒)起至现在的总毫秒数。

Java中获取方法

System.currentTimeMillis();

C#中获取方法

// 与 java 中的 System.currentTimeMillis() 值对应
(long)(DateTime.UtcNow - new DateTime(1970, 1, 1, 0, 0, 0, DateTimeKind.Utc)).TotalMilliseconds;

timestamp参数在客户端请求时在http请求头中添加，键:timestamp，值:系统当前总毫秒数。

3. 验证token

token主要用来表示用户身份，当用户在系统登录成功后，服务器会给每个用户分配一个独立无二的标识字符串，用来表示用户的身份，这样用户在后续的请求交互过程中就不再需要再传输账号和密码来验证用户的身份了，只需要带上token就可以表示用户的身份了。

token是有时间期限的，过期之后就不能继续使用，需要重新登录，重新获取用户凭证，当前系统默认分配的token有效期是一个月，一个月后自动失效，开发者可以根据情况调整有效期。

如果接口不需要验证用户的身份，属于公开接口，此时也不需要传递此参数，只有控制器或者请求方法中设置了@Authorize注解，才会验证token参数。设置了@AllowAnonymous注解的控制器或者请求方法也不需要传递此参数。

token参数在客户端请求时在http请求头中添加，键:token，值:用户凭据。

响应基本格式

{
  "success": false,
  "msg": "",
  "data": null
}

1. success

表示请求处理状态，true表示请求调用成功，false表示请求调用失败。

2. msg

如果请求调用失败msg表示错误消息，否则msg为空。

3. data

请求相关的业务数据，data可以是数字、字符串、日期、对象、集合以及可序列化的所有对象。

请求成功并返回单个字符串

{
  "success": true,
  "msg": null,
  "data": "中心服务器"
}

请求失败

{
  "success": false,
  "msg": "无效的应用程序,请按照规范请求",
  "data": null
}

请求成功并返回对象

{
  "success": true,
  "msg": null,
  "data": {
    "id": "1126748805002301440",
    "name": "是否允许重复登录",
    "code": "sys.allowRepeatLogin",
    "value": "1",
    "spell": "sfyxzfdl",
    "remark": "0 不允许重复登录 1 允许重复登录"
  }
}

请求成功并返回集合

{
  "success": true,
  "msg": null,
  "data": [
    {
      "id": "1131171578428657664",
      "code": "CustomerCategory"
    },
    {
      "id": "1131171603284103168",
      "code": "CustomerCategory"
    }
  ]
}

请求成功并返回分页集合

{
  "success": true,
  "msg": null,
  "data": {
    "total": 2,
    "pageIndex": 1,
    "pageSize": 10,
    "rows": [
      {
        "id": "1131171578428657664",
        "code": "CustomerCategory",
        "name": "公司"
      },
      {
        "id": "1131171603284103168",
        "code": "CustomerCategory",
        "name": "个人"
      }
    ]
  }
}

data.total 总记录数 data.pageIndex: 当前页码 data.pageSize: 每页大小 data.rows 数据集合

接口文档

介绍

接口规范采用swagger规范，显示方式采用swagger-bootstrap-ui组件来展示，swagger-bootstrap-ui是springfox-swagger的增强UI实现，为Java开发者在使用Swagger的时候，能拥有一份简洁、强大的接口文档体验。

文档：https://doc.xiaominfo.com/guide/
效果：http://swagger-bootstrap-ui.xiaominfo.com/doc.html
示例: https://gitee.com/xiaoym/swagger-bootstrap-ui-demo

让我们先理一下springfox与swagger的关系。
swagger是一个流行的API开发框架，这个框架以“开放API声明”（OpenAPI Specification，OAS）为基础，对整个API的开发周期都提供了相应的解决方案，是一个非常庞大的项目（包括设计、编码和测试，几乎支持所有语言）。OAS本身是一个API规范，它用于描述一整套API接口，包括一个接口是GET还是POST请求啊，有哪些参数哪些header，都会被包括在这个文件中。

springfox-swagger是使用Java语言对swagger组件的封装，swagger-bootstrap-ui是对springfox-swagger的封装。

项目接口文档地址：http://localhost:6070/doc.html

localhost:6070表示服务器IP地址和端口，要替换为实际的IP地址和端口。

调试接口

先设置全局参数设置，打开项目接口文档，路径文档管理→全局参数设置，设置appId和token

appId 使用管理员分配给的值
token 调用系统登录接口，把返回的token值写进去

保存完成后，打开任意一个接口，点击左边的调试选项卡，在参考中就可以看到刚才添加的全局参数，按要求添加其他参数后点发送按钮进行调试。

配置

要启用接口文档组件，需要在config包下面添加SwaggerConfig.java文件，并对代码内的参数进行配置，具体配置信息请参考swagger-bootstrap-ui文档内容和SwaggerConfig.java文件内的注释。

resources目录下主配置文件application.properties中与接口文档相关的配置

#是否启用文档
xci.swagger.enabled=true
#是否开启文档认证
swagger.basic.enable=true
#认证用户名
swagger.basic.username=xci
#认证密码
swagger.basic.password=xci

文档描述注解

1. 类注解

描述Controller，使用注解@Api(tags = “接口描述”)

/**
 * 设备收费标准接口
 * @author 吕艳阳
 */
@Api(tags = "设备收费标准接口")
@RestController
@RequestMapping("/api/om/basicDeviceCost")
public class BasicDeviceCostApiController extends ApiSysBaseController {
}

tags 用于资源或任何其他限定符的逻辑分组。
hidden 是否隐藏此接口，默认false。

2. 方法注解

描述方法使用注解@ApiOperation(value = “新建设备收费标准”)

@ApiOperation(value = "新建设备收费标准")
@PostMapping("/insert")
public BoolMessage insert(@RequestBody BasicDeviceCost entity) {
    return BoolMessage.success();
}

value 方法描述
hidden 是否隐藏此方法，默认false。

3. 参数注解

如果参数是对象类型，此处并不需要添加参数描述注解。

单个参数使用注解@ApiImplicitParam

@ApiOperation(value = "删除设备收费标准")
@ApiImplicitParam(name = "ids", value = "设备收费标准主键字符串,多个逗号隔开", required = true)
@PostMapping("/delete")
public BoolMessage delete(String ids) {
    return basicDeviceCostService.delete(ids);
}

多个参数使用注解组合@ApiImplicitParams和@ApiImplicitParam：

@ApiOperation(value = "查询设备收费标准列表")
@ApiImplicitParams({
    @ApiImplicitParam(name = "name", value = "名称关键字"),
    @ApiImplicitParam(name = "status", value = "状态")
})
@PostMapping("/selectList")
public BoolMessage<List<BasicDeviceCost>> selectList(String name, Boolean status) {
    return BoolMessage.success(basicDeviceCostService.selectList(name, status));
}

name 参数名称
value 参数描述
required 是否必填项，默认false。
allowableValues 允许填写的枚举值，多个值直接用逗号隔开。

4. 实体注解

如果方法传递的参数为对象类型，此时在方法上面并不需要添加参数注解。

描述对象使用注解@ApiModel(description = “对象描述信息”)。

/**
 * 客户档案
 */
@ApiModel(description = "客户档案")
public class BasicCustomer implements Serializable {
}

5. 实体属性注解

描述对象属性使用注解@ApiModelProperty(value = “属性描述”)。

/**
 * 客户姓名
 */
@ApiModelProperty(value = "客户名称", required = true)
private String name;

value 表示字段描述。
required 表示字段是必填项，默认false。
hidden 是否隐藏此字段，默认false。
position 设置字段顺序，默认值0，从小到大排序。

6. 其他

@ApiIgnore()：用于类或者方法上，用于隐藏类或者方法不显示。

@ApiSort(序号)：对接口进行排序，需要设置文档管理→个性化设置→启用SwaggerBootstrapUi提供的增强功能

@ApiOperationSort(序号)：对接口方法进行排序，需要设置文档管理→个性化设置→启用SwaggerBootstrapUi提供的增强功能