/API_Doc_Standard

API 接口文档规范 API document standard

API 接口文档规范 API document standard

 V1.0   大家有什么意见和建议,可以在issues提出。

目录

API接口规范

接口响应规范

HTTP接口遵循API协议规范。返回数据格式统一如下:

{
    "code":"", //必选,返回码
    "message":"" ,//可选,返回消息, 
    "other":""//可选
    ...
}

Api returnCode定义(一般采用http状态码)

code value
200 正常
500 服务器错误
自定义 自定义

http状态码参考 https://httpstatuses.com/

接口签名规范

待写

put php  code here

API说明

接口1

应用场景

场景1:xxxxxxxx

XX接口

描述 内容
接口功能 功能描述
请求协议 HTTP,HTTPS
请求方法 POST,GET,PUT,DELETE,HEAD,OPTIONS,PATCH.
请求格式 form url encoded,multipart form,file,json,xml...
请求url http://localhost/pushmsg?name=tom
请求头(和请求格式对应) Content-Type:application/x-www-form-urlencoded,Content-Type:application/multipart/form-data,Content-Type:application/octet-stream,Content-Type:application/json,Content-Type:application/xml...
备注 可选
请求内容 请求内容
响应码 响应码
响应头 可选
响应格式 json,xml...

请求参数,如下:

参数 描述 必填 类型
param 参数示例1 string
param2 参数示例2 int

响应参数,如下:

参数 描述 必有 类型
code 响应码 int
message 响应消息 string
param 参数示例1 string
param2 参数示例2 int

请求示例:

{
    "title": "推送标题",
    "content": "推送内容"
}

响应示例:

成功情况:

{
    "code": 200,
    "message": "成功",
     
}

失败情况

{
    "code": 500,
    "message": "失败",
    
}

可参考 : https://github.com/OAI/OpenAPI-Specification/blob/master/versions/3.0.2.md