API文档模板

此段文字是本项目OpenAPI文档的首部介绍部分，可以针对项目做适当的修改。

XXXX项目API文档

1.概述

本文档只适用于前端和后端开发使用，API内容可能会发生改变，届时后端将会与前端就具体改动进行探讨，并将最终改动方案提交到本文档。

本文档中有关数据模型的相关陈述已在后端数据文档中详细论述，请参阅后端数据文档。

本文版本，修改日期，修改内容列表如下：

2.基础规则

1.API接口

API统一使用RESTFul或类RESTful风格接口模式，（如果将来会有迭代的话，有可能）使用接口路径中的vX.X确认api版本。

应用的development环境入口为localhost:3000/。

production环境入口待定。

2.API参数

API GET请求参数部分通过Query传输（如果有需要的话）

API POST请求参数部分使用content-type: application/json类型传输

API的所有返回值均为json格式，基础结构如下

{
  "code": 0, //结果code
  "msg": "ok", //消息
  "data": [] //返回信息
}

3.API状态码code

API状态码分为两种，成功并正常返回数据为0, 其他情况为五位且遵循如下格式：

• 前两位代表出问题的微服务，目前编号如下：

  code	状态
  00	全局通用
  10	网关
  11	XXXXX后端
  12	XXXXX服务
  13	XXXXX服务

• 中间一位代表出问题的类型，目前编号如下：

  code	状态
  0	正常情况，但需要处理（通常为队列等待中）
  1	用户参数异常
  2	本服务发生异常
  3	其他服务发生异常
  4	未预料到的异常

• 最后两位代表出问题的具体信息，遵循如下规则：

  • 若为其他服务发生的异常，则为其他服务的编号
  • 若为未预料到的异常，则为00
  • 其他情况则为各微服务自定的编号

注意：当出现问题时，msg会标明错误具体消息

根据API执行成功与否，API请求的HTTP状态码会有如下类别：