{"id":21740708,"url":"https://github.com/w3yyb/api_doc_standard","last_synced_at":"2026-01-04T21:31:40.715Z","repository":{"id":88996156,"uuid":"129701995","full_name":"w3yyb/API_Doc_Standard","owner":"w3yyb","description":"API 接口文档规范 API document standard","archived":false,"fork":false,"pushed_at":"2022-02-01T06:36:55.000Z","size":26,"stargazers_count":8,"open_issues_count":0,"forks_count":8,"subscribers_count":5,"default_branch":"master","last_synced_at":"2025-01-25T21:27:53.475Z","etag":null,"topics":["api","api-documentation","json-api","rest-api","restful-api"],"latest_commit_sha":null,"homepage":"","language":null,"has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/w3yyb.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2018-04-16T07:23:34.000Z","updated_at":"2024-05-18T15:12:01.000Z","dependencies_parsed_at":"2023-06-13T11:45:15.323Z","dependency_job_id":null,"html_url":"https://github.com/w3yyb/API_Doc_Standard","commit_stats":null,"previous_names":[],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/w3yyb%2FAPI_Doc_Standard","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/w3yyb%2FAPI_Doc_Standard/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/w3yyb%2FAPI_Doc_Standard/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/w3yyb%2FAPI_Doc_Standard/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/w3yyb","download_url":"https://codeload.github.com/w3yyb/API_Doc_Standard/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":244717338,"owners_count":20498284,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["api","api-documentation","json-api","rest-api","restful-api"],"created_at":"2024-11-26T06:14:56.094Z","updated_at":"2026-01-04T21:31:40.645Z","avatar_url":"https://github.com/w3yyb.png","language":null,"readme":"# API 接口文档规范 API document standard\n \n  V1.0\n   大家有什么意见和建议，可以在issues提出。\n\n \n\n\n# 目录 \u003ca name=\"index\"/\u003e\n* [一.API接口规范](#api_standard_index)\n    * [接口响应规范](#api_resp_index)\n    * [接口签名规范](#api_sign_index)\n    * [接口请求示例](#api_demo_index)\n* [二.API说明](#api_common_index)\n    * [接口1](#api_1)\n    * [应用场景](#yycj_1_index)\n\n\n# API接口规范 \u003ca name=\"api_standard_index\"/\u003e\n## 接口响应规范 \u003ca name=\"api_resp_index\"/\u003e\n\u003e HTTP接口遵循API协议规范。返回数据格式统一如下：\n\n\n```\n{\n    \"code\":int, //必选,返回码；数字类型\n    \"message\":\"\" ,//可选，返回消息， 如ok,error, 成功\n    \"content\":{}//可选\n    ...\n}\n```\n\u003e Api returnCode定义(一般采用http状态码)\n\n\ncode|value\n---|---\n200|成功\n4xx|客户端错误\n5xx|服务器端错误\n自定义|自定义\n \n http状态码参考 https://httpstatuses.p2hp.com/\n\n\n## 接口签名规范 \u003ca name=\"api_sign_index\"/\u003e\n\u003e   为了防止提交到接口的明文泄密，可以对提交到接口的数据加密，可以用AES加密算法。微信公众平台官方API接口就是采用此算法。\n\u003e   加密方法：所有提交过来的数据都使用AES加密算法+Base64(base64UrlEncode)算法加密  \n\u003e   将签名值放在请求的参数中例如sign=ducL9jnRX1De2o15_xw6xg  \n  \n\n1.AES加密参数：\n\n加密模式:AES-128-ECB （可用更安全的aes-128-cbc-微信公众平台在用））\n\n向量iv:空 (aes-128-cbc时需要)\n\n密钥Key：“123456789”(请勿外泄)\n\n填充：PKCS7(PKCS7与PKCS5结果一样)（微信公众平台用的是PKCS7填充）\n\n2.加密步骤：\n\n对数据进行AES加密。\n\n对AES加密后的数据进行Base64(base64UrlEncode)加密。\n \n\n3.加密示例：\n\n1）原始数据：“hello world”\n\n2）AES加密后数据：“bH� �G:9�i_x0005_��”\n\n3）base64UrlEncode加密后数据：“ducL9jnRX1De2o15_xw6xg”\n参考：https://blog.p2hp.com/archives/5459 \n\n\n```php\n\u003c?php\n//$key previously generated safely, ie: openssl_random_pseudo_bytes\n$key='123456789';\n \n   /**\n     * base64UrlEncode   https://jwt.io/  中base64UrlEncode编码实现\n     * @param string $input 需要编码的字符串\n     * @return string\n     */\n     function base64UrlEncode($input)\n    {\n        return str_replace('=', '', strtr(base64_encode($input), '+/', '-_'));\n    }\n\n    /**\n     * base64UrlEncode  https://jwt.io/  中base64UrlEncode解码实现\n     * @param string $input 需要解码的字符串\n     * @return bool|string\n     */\n     function base64UrlDecode($input)\n    {\n        $remainder = strlen($input) % 4;\n        if ($remainder) {\n            $addlen = 4 - $remainder;\n            $input .= str_repeat('=', $addlen);\n        }\n        return base64_decode(strtr($input, '-_', '+/'));\n    }\n$plaintext=\"hello world\";\n //$cipher = \"aes-128-cbc\";\n $cipher = \"aes-128-ecb\";\n\nif (in_array($cipher, openssl_get_cipher_methods()))\n{\n     \n     \n    // $iv='1111111111111111';\n    $iv='';\n    $ciphertext = openssl_encrypt($plaintext, $cipher, $key, OPENSSL_RAW_DATA, $iv);//如果去掉OPENSSL_RAW_DATA参数,则直接输出base64编码的,不用再base64编码\n    $ciphertext =base64UrlEncode($ciphertext);\n    //store $cipher, $iv, and $tag for decryption later\n    $original_plaintext = openssl_decrypt(base64UrlDecode($ciphertext), $cipher, $key, OPENSSL_RAW_DATA, $iv);\n\n\n    var_dump( $original_plaintext);\n    var_dump( $ciphertext);\n}\n```\n \n## 接口请求示例 \u003ca name=\"api_demo_index\"/\u003e\n\n```\nPOST http://server-api.xxx.com/api?sign=ducL9jnRX1De2o15_xw6xg HTTP/1.1\nHost: server-api.xxx.com\nConnection: keep-alive\nContent-Length: 226\nCache-Control: no-cache\nContent-Type: application/json\nAccept: */*\nAccept-Encoding: gzip, deflate\nAccept-Language: zh-CN,zh;q=0.8\n\n{\"title\":\"xxxx\",\"content\":\"xxxxxxx\"}\n\n\nHTTP/1.1 200 OK\nServer: nginx\nDate: Wed, 28 Dec 2016 03:34:53 GMT\nContent-Type: application/json; charset=UTF-8\nContent-Length: 87\nConnection: keep-alive\nContent-Language: zh-CN\nSet-Cookie: JSESSIONID=1wl3nhcfqroiicj6pvxwdvjx6;Path=/\nExpires: Thu, 01 Jan 1970 00:00:00 GMT\n\n\n{\"code\":200,\"message\":\"ok\",\"content\":{\"data\":[\"xxxxxx\"]}}\n```\n\n\n\n# API说明 \u003ca name=\"api_common_index\"/\u003e\n \n\n## 接口1 \u003ca name=\"api_1\"/\u003e\n### 应用场景 \u003ca name=\"yycj_1_index\"/\u003e\n\n\u003e 场景1：xxxxxxxx\n\n\n\n### XX接口 \u003ca name=\"UnVarnishedMessage_push_index\"/\u003e\n\n描述|内容\n---|---\n接口功能|功能描述\n请求协议|HTTP,HTTPS\n请求方法|POST,GET,PUT,DELETE,HEAD,OPTIONS,PATCH.\n请求格式|form url encoded,multipart form,file,json,xml...\n请求url| http://localhost/pushmsg?sign=xxxxxxxxxxxxx\n请求头(和请求格式对应)|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...\n备注|可选\n请求内容|请求内容\n响应码|响应码\n响应头|可选\n响应格式|json,xml...\n响应内容|可选\n\n\n请求参数,如下:\n\n参数|描述|必填|类型\n---|---|---|---\nsign|签名|是|string\nparam|参数示例1|是|string\nparam2|参数示例2|是|int\n\n\n 响应参数,如下:\n\n参数|描述|必有|类型\n---|---|---|---\ncode|响应码|是|int\nmessage|响应消息|否|string\ncontent|响应内容|否|json\n \n 请求示例：\n\n```\n{\n    \"title\": \"推送标题\",\n    \"content\": \"推送内容\"\n}\n```\n\n响应示例：\n\n\u003e 成功情况：\n\n```\n{\n    \"code\": 200,\n    \"message\": \"成功\",\n    \"content\":{\"title\":\"text\"}\n     \n}\n```\n\n\u003e 失败情况\n\n\n```\n{\n    \"code\": 500,\n    \"message\": \"失败\",\n    \"content\":{\"title\":\"text\"}\n    \n}\n```\n \n 安全加强：IP白名单，限速，token过期时间。\n\n 可参考  ： https://github.com/OAI/OpenAPI-Specification/blob/master/versions/3.0.2.md\n","funding_links":[],"categories":[],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fw3yyb%2Fapi_doc_standard","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fw3yyb%2Fapi_doc_standard","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fw3yyb%2Fapi_doc_standard/lists"}