README

MyParcel.com使用的API规范描述，位于https://api-specification.myparcel.com。本规范遵循OpenApi 3.0规范并实现了JSON API规范。

内容

安装
命令
约定
许可证

安装

该存储库提供了Docker容器以在提交更改之前验证和预览规范。这也在验证拉取请求时使用。要安装Docker，请按照文档中的步骤操作。

要为开发设置项目，请运行

./mp.sh setup

命令

./mp.sh up - 启动容器，这将启动一个服务器以监视文件更改并自动重新加载。

./mp.sh down - 停止容器。

./mp.sh validate - 验证规范。

注意：验证器仅在容器已运行时才有效。不要忘记启动它们。

约定

基于Swagger和JSON Schema规范的约定。

我们的内部约定如下所述。

PUT, POST, PATCH

为了避免讨论，下面描述了上述HTTP方法的用法。

`PUT`

用于创建或替换资源。
在重复请求上始终返回相同的响应。
需要请求中的完整资源（包括要创建或替换的资源id）。

`POST`

用于创建资源。
在重复请求上不返回相同的响应。
不需要请求中的完整资源（通常不需要要创建的资源id）。

`PATCH`

用于更新现有资源。
在重复请求上不返回相同的响应。
不需要请求中的完整资源（例如，可能只想更新用户的名字）。

API版本化

API版本化遵循语义版本化。版本号的增加是手动进行的，并应作为拉取请求的一部分。

Schema文件命名

定义文件名遵循PascalCasing约定。每个单词的第一个字母（包括第一个单词）都是大写。例如，国家代码的定义可以在以下位置找到：

specification/schemas/CountryCode.json

路径文件命名

specification/paths中的文件以它们对应的API端点命名。其中资源以大写字母开头，路径变量以小写字母开头。例如，以下路由的定义可以在以下位置找到：

carriers/{carrier_id}/services

可以找到：

specification/paths/Carriers-carrier_id-Services.json

参数文件命名

参数文件名以相应的参数类型为前缀。对于carrier_id的路径参数，将得到以下文件路径：

specification/parameters/path-carrier_id.json

唯一的参数可以直接保留在路径文件中，不需要提取到它们自己的文件中。

许可证

MyParcel.com的所有软件均根据MyParcel.com通用条款和条件进行许可。

myparcelcom / api-specification

维护者

详情