json接口文档模板_API设计指南-「干货」一个接口文档模板的最佳实践

1. 基础说明

1.1 背景

[说明文档用途]

编写本文的目的是为了将系统功能进行模块化、服务化，将用户的操作以服务的方式提供。系统与系统之间遵循服务规范，将系统与系统之间的交互转为定制化服务交互，以实现系统与系统之间的集成。

1.2 基本约束

1.2.1 基本设计原则

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

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&