phpapi接口文档模板技巧_API设计指南干货一个接口文档模板的最佳实践

文章目录 [+]

编写本文的目的是为了将系统功能进行模块化、做事化，将用户的操作以做事的办法供应。
系统与系统之间遵照做事规范，将系统与系统之间的交互转为定制化做事交互，以实现系统与系统之间的集成。

1.2 基本约束1.2.1 基本设计原则

请参考上一篇文章《API设计指南-RestAPI设计最佳实践》。

phpapi接口文档模板技巧_API设计指南干货一个接口文档模板的最佳实践

1.2.2 字符集所有接口字符集采取UTF-8。
1.2.3 返回类型约束所有接口返回必须是严格定义的JSON类型。
1.2.4 接口版本约束不许可发布无版本号的接口。
接口版本首先办理的是一组接口的版本问题。
1.3 要求公共约束

要求的基本模板：

（图片来自网络侵删）

curl -X[HTTP METHOD] -H "Content-Type: application/json" -H "[token-info]:""https://api-[env-name].[groupname].domain.io/[client-group]/[service-group]/[version]/[endpoint]" -d '{ "head": [meta-parameters], "body": [content]}'1.4 URL整体方案1.4.1 域名规范https://api-[env-name].[groupname].domain.io/[client-group]/[service-group]/[version]/[endpoint]1.4.2 域名规则开拓环境：https://api-dev.payment.domain.io/测试环境：https://api-test.payment.domain.io/预演环境：https://api-staging.payment.domain.io/线上测试环境：https://api-onlinetest.payment.domain.io/生产环境：https://api.payment.domain.io/个中线上测试环境是上线过程中备用，比如线上一共3台生产环境做事器，将个中一台从生产环境切掉，更新程序并且将域名指向它，测试完之后再将生产环境流量切换过来。
1.5 基本数据类型约定

此约定是系统整体容错的一部分，但是无论接口利用者还是生产者，都不应该由于此容错而减少自己模块本来须要的容错事情。

1.6 公共输入参数规范

1.7 公共返回工具约定

{ "responseCode": [responseCode], "responseInfo": { "userMessage": [userMessage], "internalMessage": [internalMessage], "guideline": [guideline link] }, "link": { "document":" https://[domain]/docs#zoos", "href":[uri-info], "title":[doc-title], "type":"application/[vnd.yourformat]+json" }, "responseData":[responseData]}1.8 公共缺点编码及解释

1.9 公共数据字典

2. 订单做事2.1 查询订单列表2.1.1 接口规范

2.1.2 输入参数示范

curl -XGET -H "Content-Type: application/json" -H "Access-Token:abcd1234" "https://api-dev.haitao.domain.io/mobile/data-platform/v1/orders/base-orders" -d '{ "head": [meta-parameters], "body": { "pageSize":10, "pageNo":1 }}'2.1.3 返回参数示范