https://github.com/w3yyb/api_doc_standard
API 接口文档规范 API document standard
https://github.com/w3yyb/api_doc_standard
api api-documentation json-api rest-api restful-api
Last synced: 3 months ago
JSON representation
API 接口文档规范 API document standard
- Host: GitHub
- URL: https://github.com/w3yyb/api_doc_standard
- Owner: w3yyb
- Created: 2018-04-16T07:23:34.000Z (about 7 years ago)
- Default Branch: master
- Last Pushed: 2022-02-01T06:36:55.000Z (over 3 years ago)
- Last Synced: 2025-01-25T21:27:53.475Z (5 months ago)
- Topics: api, api-documentation, json-api, rest-api, restful-api
- Homepage:
- Size: 25.4 KB
- Stars: 8
- Watchers: 5
- Forks: 8
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
Awesome Lists containing this project
README
# API 接口文档规范 API document standard
V1.0
大家有什么意见和建议，可以在issues提出。
# 目录
* [一.API接口规范](#api_standard_index)
* [接口响应规范](#api_resp_index)
* [接口签名规范](#api_sign_index)
* [接口请求示例](#api_demo_index)
* [二.API说明](#api_common_index)
* [接口1](#api_1)
* [应用场景](#yycj_1_index)
# API接口规范
## 接口响应规范
> HTTP接口遵循API协议规范。返回数据格式统一如下：
```
{
"code":int, //必选,返回码；数字类型
"message":"" ,//可选，返回消息， 如ok,error, 成功
"content":{}//可选
...
}
```
> Api returnCode定义(一般采用http状态码)
code|value
---|---
200|成功
4xx|客户端错误
5xx|服务器端错误
自定义|自定义
http状态码参考 https://httpstatuses.p2hp.com/
## 接口签名规范
> 为了防止提交到接口的明文泄密，可以对提交到接口的数据加密，可以用AES加密算法。微信公众平台官方API接口就是采用此算法。
> 加密方法：所有提交过来的数据都使用AES加密算法+Base64(base64UrlEncode)算法加密
> 将签名值放在请求的参数中例如sign=ducL9jnRX1De2o15_xw6xg
1.AES加密参数：
加密模式:AES-128-ECB （可用更安全的aes-128-cbc-微信公众平台在用））
向量iv:空 (aes-128-cbc时需要)
密钥Key：“123456789”(请勿外泄)
填充：PKCS7(PKCS7与PKCS5结果一样)（微信公众平台用的是PKCS7填充）
2.加密步骤：
对数据进行AES加密。
对AES加密后的数据进行Base64(base64UrlEncode)加密。
3.加密示例：
1）原始数据：“hello world”
2）AES加密后数据：“bH� �G:9�i_x0005_��”
3）base64UrlEncode加密后数据：“ducL9jnRX1De2o15_xw6xg”
参考：https://blog.p2hp.com/archives/5459
```php
```
POST http://server-api.xxx.com/api?sign=ducL9jnRX1De2o15_xw6xg HTTP/1.1
Host: server-api.xxx.com
Connection: keep-alive
Content-Length: 226
Cache-Control: no-cache
Content-Type: application/json
Accept: */*
Accept-Encoding: gzip, deflate
Accept-Language: zh-CN,zh;q=0.8
{"title":"xxxx","content":"xxxxxxx"}
HTTP/1.1 200 OK
Server: nginx
Date: Wed, 28 Dec 2016 03:34:53 GMT
Content-Type: application/json; charset=UTF-8
Content-Length: 87
Connection: keep-alive
Content-Language: zh-CN
Set-Cookie: JSESSIONID=1wl3nhcfqroiicj6pvxwdvjx6;Path=/
Expires: Thu, 01 Jan 1970 00:00:00 GMT
{"code":200,"message":"ok","content":{"data":["xxxxxx"]}}
```
> 场景1：xxxxxxxx
描述|内容
---|---
接口功能|功能描述
请求协议|HTTP,HTTPS
请求方法|POST,GET,PUT,DELETE,HEAD,OPTIONS,PATCH.
请求格式|form url encoded,multipart form,file,json,xml...
请求url| http://localhost/pushmsg?sign=xxxxxxxxxxxxx
请求头(和请求格式对应)|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...
响应内容|可选
请求参数,如下:
参数|描述|必填|类型
---|---|---|---
sign|签名|是|string
param|参数示例1|是|string
param2|参数示例2|是|int
响应参数,如下:
参数|描述|必有|类型
---|---|---|---
code|响应码|是|int
message|响应消息|否|string
content|响应内容|否|json
请求示例：
```
{
"title": "推送标题",
"content": "推送内容"
}
```
响应示例：
> 成功情况：
```
{
"code": 200,
"message": "成功",
"content":{"title":"text"}
}
```
> 失败情况
```
{
"code": 500,
"message": "失败",
"content":{"title":"text"}
}
```
安全加强：IP白名单，限速，token过期时间。
可参考 ： https://github.com/OAI/OpenAPI-Specification/blob/master/versions/3.0.2.md