宠物商店 API 文档

宠物商店 API 遵循 REST 标准进行设计。
我们的 API 是可预期的以及面向资源的，接受 form-encoded 请求正文，返回 JSON-encoded 响应，使用标准的 HTTP 响应代码，认证（OAuth 2.0）和参数。
所有请求和响应的编码均为 UTF-8。

基础路径

API BASE URL

https://petstore.com/api/v1
生产环境
http://test.petstore.com/api/v1
测试环境

调用说明

请求

所有的请求方式（Method）均与动词相关：

GET：获取资源
POST：创建资源
PUT：更新资源
PATCH：更新资源的一个属性
DELETE：删除资源
OPTIONS：获取客户端能对资源做什么操作的信息

参数传入方式

如无特别说明，GET 请求参数需要放到 Url Query String 中：

GET https://petstore.com/api/v1/pets?pagesize=20

POST/PUT/PATCH 请求参数建议使用 JSON 格式将参数放到请求体中：

PUT https://petstore.com/api/v1/pets/1
Content-Type: application/json
{
  "id": 1,
  "category": {
    "name": "金毛",
    "id": 1
  },
  "status": "available",
  "photoUrls": [
    "http://petstore.com/1.png"
  ],
  "name": "doggie",
  "isHealthy": true,
  "tags": [
    {
      "id": 1,
      "name": "狗狗"
    }
  ]
}

响应

成功响应中包含实体资源内容，如：

[
  {
    "a": "xxx",
    "b": "xxx"
  },
  {
    "c": "xxx",
    "d": "xxx"
   }
]

认证

本 API 使用 OAuth 2.0 作为授权方式，OAuth 2.0 是一种授权协议，可让您的应用程序获取到宠物商店用户中的各种详细信息，而无需获取用户的密码。

您的应用程序在用户授权时会询问特定的授权范围，并在用户批准后获得访问权限。

在您开始之前需要先注册您的应用程序，注册完成后系统将分配给您唯一的 Client ID 和 Client Secret，用于 OAuth 授权。请注意，Client Secret 需要妥善保存，不可分享给他人。

OAuth 流程

本 API 使用 OAuth 2.0 的 Authorization Code 模式作为获取 Access Token 方式。

OAuth 流程是获取 Access Token 的关键。在没有用户授权的情况下，接口访问方是无法获取任何服务资源的。

第 1 步 - 跳转用户授权

上图步骤 1 中，您的应用应将用户重定向到以下地址：

https://petstore.com/oauth/authorize

以下值应作为 GET 参数传递：

response_type：授权类型，此处的值固定为 code（必选）
client_id：在您注册应用程序时得到的 Client ID（必选）
scope：请求权限范围，多个权限使用空格分隔（见下文）（必选）
redirect_uri：授权完成后重定向至的 URL，即您的应用程序用于接受授权结果的地址（必选）
state：完成授权后传回的唯一字符串，认证服务器会原封不动地返回这个值，防止伪造攻击（可选）

范例：

GET https://petstore.com/oauth/authorize?response_type=code&client_id=s6BhdRkqt3&state=xyz
      &scope=store%20pet&redirect_uri=https%3A%2F%2Fclient%2Eexample%2Ecom%2Fcb

第 2 步 - 使用授权码（code）将用户重定向到您的应用服务器

上图步骤 2 中，用户授权完成，将会重定向至 redirect_uri 指定的 URI，并带上以下参数：

code：表示授权码（必选）
state：如果步骤 1 客户端请求中包含该参数，步骤 2 重定向地址中也必须一模一样包含该参数（可选）

授权代码只能交换一次，并在签发后10分钟到期。该码与 client_id 是一一对应关系。

范例：

HTTP/1.1 302 Found
Location: https://client.example.com/cb?code=SplxlOBeZQQYbYS6WxSbIA
          &state=xyz

第 3 步 - 使用授权码（code）交换访问令牌（Access Token）

上图步骤 3 中，您的应用程序服务器可通过获取的授权码（code）请求 /api/token 接口以获取 Access Token。

接口地址如下：

https://petstore.com/oauth/token

接口参数如下：

grant_type：表示使用的授权模式，此处的值固定为 authorization_code（必选）
code：表示上一步获得的授权码（必选）
client_id：在您注册应用程序时得到的 Client ID（必选）
client_secret ：在您注册应用程序时得到的 Client Secret（必选）

范例：

POST https://petstore.com/oauth/token?grant_type=authorization_code&code=SplxlOBeZQQYbYS6WxSbIA&client_id=s6BhdRkqt3&client_secret=cwouf803ghv3op4ch32cu39djfhwpuow

上图步骤 4 中，您将接收到一个包含访问令牌 Access Token（以及其他详细信息）的 JSON 响应，范例如下：

HTTP/1.1 200 OK
Content-Type: application/json;charset=UTF-8
Cache-Control: no-store
Pragma: no-cache

{
    "access_token": "xoxp-23984754863-2348975623103",
    "expires_in": 86400,
    "scope": "store pet",
    "refresh_token": "tGzv3JOkF0XG5Qx2TlKWIA"
}

访问令牌默认 86400 秒过期，即 1 天，过期后您可继续使用刷新令牌（Refresh Token），通过刷新访问令牌接口 /oauth/token?grant_type=refresh_token&refresh_token={Refresh Token} 获取新的访问令牌。

第 4 步 - 使用访问令牌访问 API 资源

上图步骤 5 中，您可以使用访问令牌代表用户调用本文档对应权限（Scope）的 API 方法。

请求范例：

GET https://petstore.com/api/v1/pets?token=xoxp-23984754863-2348975623103

若访问令牌有效，宠物商店服务端将返回给应用程序对应的宠物列表。

作用域 Scopes

作用域允许你提供你想要的资源类型，这些将在用户授权表单页面显示。

对应的作用域可在对应接口文档中找到。

请求限制

为了防止拒绝服务攻击，宠物商店 API 制定了一定的限流策略，规则如下：

访问令牌无效的请求，每分钟可请求 10 次
访问令牌有效的请求，每分钟可请求 300 次

为了方便您查询当前限流的情况，你可通过响应的 Header 的 Rate Limit 参数查看，参数如下：

X-RateLimit-Remaining：剩余可请求数量
X-RateLimit-Limit：限制可请求数量
X-Ratelimit-Reset：重置限制次数时间（秒）
X-Ratelimit-Retry-After：触达限流后需要等待重置的时间（秒）

范例：

X-RateLimit-Remaining: 298
X-RateLimit-Limit: 300
X-Ratelimit-Reset: 580

超出限流限制会返回如下错误：

Header:
X-RateLimit-Remaining: 0
X-RateLimit-Limit: 300
X-Ratelimit-Reset: 230
X-Ratelimit-Retry-After: 360

{
  "message": "操作过于频繁，请稍后再试。"
}

错误

宠物商店 API 使用标准 HTTP 响应码（Status Code）来表示 API 请求。

通常，状态码：

2xx 代表成功响应
4xx 代表失败响应，并给出失败原因
5xx 代表宠物商店服务端内部错误

状态码说明

状态码	描述
200	更新/获取资源成功
201	创建资源成功
204	删除资源成功
400	业务错误，具体参见下方业务错误代码
401	认证失败，请返回认证检查参数是否有误
403	无权限调用接口，如：未开通 API 功能
404	资源不存在
405	接口请求方式 `Method` 有误
422	请求参数校验失败
429	触达限流限制
500	服务器应用发生了错误
502	服务器无法连接
503	服务器暂不可用
504	服务器连接超时

业务错误说明

状态码 4xx 的业务错误可通过编码来分别处理不同的处理逻辑，响应将通过 JSON 形式返回，其中包括业务错误码 code 和错误原因 message，例如：

{
  "code": 3001,
  "type": "ERROR",
  "message": "用户名已被占用，请更改后重新提交"
}

业务错误码 code 说明如下：

状态码 400

错误码	描述
3000	用户名或密码错误
3001	用户名已被占用，请更改后重新提交

状态码 422

错误码	描述
2000	categoryId 必填
2001	categoryId 必须为 int
2002	petId 必须为整数
2003	pagesize 必须大于 0
2004	status 不存在，必须为 placed, approevd, delivered 其中之一
2005	password 必填

版本

在极少数情况下，我们需要针对某些接口做一些破坏性的修改，为了尽量避免破坏向后兼容性，我们通过修改接口版本号来实现多版本共存，不去破坏上一版本的接口参数及逻辑，以新版本接口的形式提供同一接口不同请求或返回形式。

例如，/api/v1/users 升级后将变成 /api/v2/users

字段类型

在文档中，我们将使用许多不同类型的数据。您可以在下方的说明列表找到它们的解释及含义。

类型	定义	范例
int	整数，不带小数的数字。	1234
float	浮点数，带小数的数字。	1234.12
string	字符串是用于表示文本的字符序列。	"CODING"
boolean	布尔值，是 `true` 或 `false` 中的一个，所对应的关系就是真与假的概念。	true
time	表示日期和时间的字符串。	"2017-09-10 12:23:01"
array	列表，该列表为数组，数组中的每一项的类型由中括号内的字段类型决定。	["CODING", "VERY", "GOOD"]
object	资源，可从对应的资源 XX 对象中找到。	{"id": 1,"name": "NPC小明"}

API REFERENCE

宠物

所有关于宠物的内容

宠物列表

列出所有宠物信息

get/pets

请求 Request

QUERY

pagesizeint
默认值：20
限制每页返回数量（最大限制：100）
pageint
默认值：1
页码

响应 Response

成功返回

状态码 200

HEADER

X-PAGESIZEint
限制每页返回数量
X-PAGEint
当前页码

参数

array
宠物信息
- 数组成员object
- idint
  ID
- categoryobject必填
  Category
  
  宠物分类
  - 子属性
  - category.namestring必填
    名称
- statusstring
  可选值：available , pending , sold
  |
  string
  状态
- photoUrlsarray
  照片地址列表
  - 数组成员string
  - 照片地址
- namestring
  名称
- isHealthyboolean
  是否健康
- tagsarray
  标签列表
  - 数组成员object
  - tags.idint
    ID
  - tags.namestring
    名称

错误返回

状态码 422

参数

codeint
消息码
typestring
可选值：SUCCESS , ERROR
|
string
类型
messagestring
异常信息

Example 1

请求示例

文本

get

{{BASE_URL}}/pets?pagesize=20&page=1

成功示例

以数组形式返回宠物信息

1[
2  {
3    "id": 1,
4    "category": {
5      "id": 1,
6      "name": "金毛"
7    },
8    "status": "available",
9    "photoUrls": [
10      "http://petstore.com/1.png"
11    ],
12    "name": "doggie",
13    "isHealthy": true,
14    "tags": [
15      {
16        "id": 1,
17        "name": "狗狗"
18      }
19    ]
20  },
21  {
22    "id": 2,
23    "category": {
24      "id": 1,
25      "name": "金毛"
26    },
27    "status": "available",
28    "photoUrls": [
29      "http://petstore.com/2.png"
30    ],
31    "name": "gucci",
32    "isHealthy": true,
33    "tags": [
34      {
35        "id": 1,
36        "name": "狗狗"
37      }
38    ]
39  }
40]

失败示例

参数有误

1{
2  "code": 2003,
3  "type": "ERROR",
4  "message": "pagesize 必须大于 0"
5}

新增宠物

新增宠物操作

post/pets

请求 Request

请求 BODY

categoryIdint必填
分类 ID
statusstring
可选值：available , pending , sold
|
默认值：available
|
string
状态
photoUrlsarray必填
照片地址列表
- 数组成员string
- 照片地址
namestring必填
宠物名称
isHealthyboolean
默认值：true
|
boolean
是否健康
tagIdsarray
标签 ID 数组
- 数组成员int
- 标签 ID

响应 Response

成功返回

状态码 201

参数

idint
ID
categoryobject
Category

宠物分类
- 子属性
- category.namestring必填
  名称
statusstring
可选值：available , pending , sold
|
string
状态
photoUrlsarray
照片地址列表
- 数组成员string
- 照片地址
namestring
名称
isHealthyboolean
是否健康
tagsarray
标签列表
- 数组成员object
- tags.idint
  ID
- tags.namestring
  名称

错误返回 1

状态码 400

错误返回 2

点击展开

Example 1

成功示例

文本

post

{{BASE_URL}}/pets

成功示例

创建成功

1{
2  "id": 1,
3  "category": {
4    "name": "金毛",
5    "id": 1
6  },
7  "status": "available",
8  "photoUrls": [
9    "http://petstore.com/1.png"
10  ],
11  "name": "doggie",
12  "isHealthy": true,
13  "tags": [
14    {
15      "id": 1,
16      "name": "狗狗"
17    }
18  ]
19}

失败示例

传入参数有误

1{
2  "code": 2000,
3  "type": "ERROR",
4  "message": "categoryId 必填"
5}

宠物详情

获取指定 ID 的宠物详情

get/pets/{petId}

请求 Request

HEADER

Acceptstring
可选值：application/json , application/xml
|
默认值：application/json
|
string
返回数据媒体类型

路由参数

petIdstring
宠物 ID

响应 Response

成功返回

状态码 200

HEADER

Content-Typestring
可选值：application/json , application/xml
|
string
媒体类型

参数

idint
ID
categoryobject
Category

宠物分类
- 子属性
- category.namestring必填
  名称
statusstring
可选值：available , pending , sold
|
string
状态
photoUrlsarray
照片地址列表
- 数组成员string
- 照片地址
namestring
名称
isHealthyboolean
是否健康
tagsarray
标签列表
- 数组成员object
- tags.idint
  ID
- tags.namestring
  名称

错误返回 1

状态码 400

错误返回 2

点击展开

Example 1

请求示例

文本

get

{{BASE_URL}}/pets/string

成功示例

宠物详情成功返回

1{
2  "id": 1,
3  "category": {
4    "name": "金毛",
5    "id": 1
6  },
7  "status": "available",
8  "photoUrls": [
9    "http://petstore.com/1.png"
10  ],
11  "name": "doggie",
12  "isHealthy": true,
13  "tags": [
14    {
15      "id": 1,
16      "name": "狗狗"
17    }
18  ]
19}

成功示例

宠物详情成功返回

1<?xml version="1.0" ?>
2<Pet>
3  <id>1</id>
4  <category>
5    <id>1</id>
6    <name>金毛</name>
7  </category>
8  <name>doogie</name>
9  <photoUrls>http://petstore.com/1.png</photoUrls>
10  <isHealthy>true</isHealthy>
11  <tags>
12    <id>1</id>
13    <name>狗狗</name>
14  </tags>
15  <status>available</status>
16</Pet>

失败示例

更新宠物信息

全量更新宠物信息

put/pets/{petId}

请求 Request

路由参数

petIdstring
宠物 ID

请求 BODY

categoryIdint必填
分类 ID
statusstring必填
可选值：available , pending , sold
|
string
状态
photoUrlsarray必填
照片地址列表
- 数组成员string
- 照片地址
namestring必填
宠物名称
isHealthyboolean必填
是否健康
tagIdsarray必填
标签 ID 数组
- 数组成员int
- 标签 ID

响应 Response

成功返回

状态码 200

参数

idint
ID
categoryobject
Category

宠物分类
- 子属性
- category.namestring必填
  名称
statusstring
可选值：available , pending , sold
|
string
状态
photoUrlsarray
照片地址列表
- 数组成员string
- 照片地址
namestring
名称
isHealthyboolean
是否健康
tagsarray
标签列表
- 数组成员object
- tags.idint
  ID
- tags.namestring
  名称

错误返回 1

状态码 400

错误返回 2

点击展开

错误返回 3

点击展开

Example 1

成功示例

文本

put

{{BASE_URL}}/pets/{petId}

成功示例

更新成功

1{
2  "id": 1,
3  "category": {
4    "name": "金毛",
5    "id": 1
6  },
7  "status": "sold",
8  "photoUrls": [
9    "http://petstore.com/1.png"
10  ],
11  "name": "doggie",
12  "isHealthy": true,
13  "tags": [
14    {
15      "id": 1,
16      "name": "狗狗"
17    }
18  ]
19}

失败示例

传入参数有误

1{
2  "code": 2001,
3  "type": "ERROR",
4  "message": "categoryId 必须为 int"
5}

单独更新宠物属性废弃

单独更新宠物属性

patch/pets/{petId}

请求 Request

路由参数

petIdstring
宠物 ID

请求 BODY

categoryIdint
分类 ID
statusstring
可选值：available , pending , sold
|
string
状态
photoUrlsarray
照片地址列表
- 数组成员string
- 照片地址
namestring
宠物名称
isHealthyboolean
是否健康
tagIdsstring
标签 ID 数组

响应 Response

成功返回

状态码 200

参数

idint
ID
categoryobject
Category

宠物分类
- 子属性
- category.namestring必填
  名称
statusstring
可选值：available , pending , sold
|
string
状态
photoUrlsarray
照片地址列表
- 数组成员string
- 照片地址
namestring
名称
isHealthyboolean
是否健康
tagsarray
标签列表
- 数组成员object
- tags.idint
  ID
- tags.namestring
  名称

错误返回 1

状态码 400

错误返回 2

点击展开

错误返回 3

点击展开

Example 1

成功示例

文本

patch

{{BASE_URL}}/pets/{petId}

成功示例

更新成功

1{
2  "id": 1,
3  "category": {
4    "name": "金毛",
5    "id": 1
6  },
7  "status": "sold",
8  "photoUrls": [
9    "http://petstore.com/1.png"
10  ],
11  "name": "doggie",
12  "isHealthy": true,
13  "tags": [
14    {
15      "id": 1,
16      "name": "狗狗"
17    }
18  ]
19}

失败示例

传入参数有误

1{
2  "code": 2001,
3  "type": "ERROR",
4  "message": "categoryId 必须为 int"
5}

删除宠物

删除宠物操作

delete/pets/{petId}

请求 Request

路由参数

petIdstring
宠物 ID

响应 Response

成功返回

状态码 204

参数

codeint
消息码
typestring
可选值：SUCCESS , ERROR
|
string
类型
messagestring
异常信息

错误返回 1

状态码 400

错误返回 2

点击展开

Example 1

请求示例

文本

delete

{{BASE_URL}}/pets/string

成功示例

删除成功

1{
2  "code": 0,
3  "type": "SUCCESS",
4  "message": ""
5}

失败示例

上传照片

上传照片接口

post/pets/{petId}/uploadImage

请求 Request

HEADER

Content-Typestring必填
可选值：application/octet-stream
|
string
媒体类型

路由参数

petIdstring
宠物 ID

请求 BODY

file必填
binary 形式上传文件

响应 Response

成功返回

状态码 200

参数

codeint
消息码
typestring
可选值：SUCCESS , ERROR
|
string
类型
messagestring
异常信息

错误返回 1

状态码 400

错误返回 2

点击展开

Example 1

请求示例

文本

post

{{BASE_URL}}/pets/string/uploadImage

成功示例

JSON 正常返回

1{
2  "code": 0,
3  "type": "SUCCESS",
4  "message": ""
5}

失败示例

使用 form-data 上传照片

post/pets/{petId}/uploadFormImage

请求 Request

HEADER

Content-Typestring必填
可选值：multipart/form-data
|
string
媒体类型

路由参数

petIdstring
宠物 ID

请求 BODY

filefile必填
binary 文件

响应 Response

成功返回

状态码 200

参数

codeint
消息码
typestring
可选值：SUCCESS , ERROR
|
string
类型
messagestring
异常信息

错误返回 1

状态码 400

错误返回 2

点击展开

Example 1

请求示例

文本

post

{{BASE_URL}}/pets/string/uploadFormImage

成功示例

1{
2  "code": 0,
3  "type": "SUCCESS",
4  "message": ""
5}

失败示例

商店订单

可查看宠物商店的订单

新建宠物订单

post/orders

请求 Request

HEADER

Content-Typestring必填
可选值：application/json
|
string
媒体类型

请求 BODY

petIdint必填
宠物 ID
shipDatestring必填
配送日期

响应 Response

成功返回

状态码 200

参数

idint
订单 ID
petobject
Pet

宠物实体信息
- 子属性
- pet.idint
  ID
- pet.categoryobject必填
  Category
  
  宠物分类
  - 子属性
  - category.namestring必填
    名称
- pet.statusstring
  可选值：available , pending , sold
  |
  string
  状态
- pet.photoUrlsarray
  照片地址列表
  - 数组成员string
  - 照片地址
- pet.namestring
  名称
- pet.isHealthyboolean
  是否健康
- pet.tagsarray
  标签列表
  - 数组成员object
  - tags.idint
    ID
  - tags.namestring
    名称
shipDatestring
配送日期
statusstring
可选值：placed , approevd , delivered
|
string
订单状态
completedboolean
订单是否完成

错误返回 1

状态码 400

参数

codeint
消息码
typestring
可选值：SUCCESS , ERROR
|
string
类型
messagestring
异常信息

错误返回 2

点击展开

Example 1

成功示例

文本

post

{{BASE_URL}}/orders

成功示例

新建成功

1{
2  "id": 1,
3  "pet": {
4    "id": 1,
5    "category": {
6      "name": "金毛"
7    },
8    "status": "available",
9    "photoUrls": [
10      "http://petstore.com/1.png"
11    ],
12    "name": "doggie",
13    "isHealthy": true,
14    "tags": [
15      {
16        "id": 1,
17        "name": "狗狗"
18      }
19    ]
20  },
21  "shipDate": "2019-08-26",
22  "status": "placed",
23  "completed": false
24}

失败示例

宠物不存在

1{
2  "code": 1001,
3  "type": "ERROR",
4  "message": "petId 对应资源不存在"
5}

失败示例

参数校验不通过

1{
2  "code": 2002,
3  "type": "ERROR",
4  "message": "petId 必须为整数"
5}

宠物订单列表

get/orders

请求 Request

QUERY

shipDatestring
配送日期（YYYY-MM-DD）
statusstring
可选值：placed , approevd , delivered
|
string
状态
completedboolean
订单是否完成

响应 Response

成功返回

状态码 200

参数

array
- 数组成员object
- idint
  订单 ID
- petobject
  Pet
  
  宠物实体信息
  - 子属性
  - pet.idint
    ID
  - pet.categoryobject必填
    Category
    
    宠物分类
    子属性
    category.namestring必填
    名称
  - pet.statusstring
    可选值：available , pending , sold
    |
    string
    状态
  - pet.photoUrlsarray
    照片地址列表
    数组成员string
    照片地址
  - pet.namestring
    名称
  - pet.isHealthyboolean
    是否健康
  - pet.tagsarray
    标签列表
    数组成员object
    tags.idint
    ID
    tags.namestring
    名称
- shipDatestring
  配送日期
- statusstring
  可选值：placed , approevd , delivered
  |
  string
  订单状态
- completedboolean
  订单是否完成

错误返回 1

状态码 422

参数

codeint
消息码
typestring
可选值：SUCCESS , ERROR
|
string
类型
messagestring
异常信息

错误返回 2

点击展开

Example 1

请求示例

文本

get

{{BASE_URL}}/orders?shipDate=string&status=placed&completed=true

成功示例

请求成功

1[
2  {
3    "id": 1,
4    "pet": {
5      "id": 1,
6      "category": {
7        "name": "金毛"
8      },
9      "status": "available",
10      "photoUrls": [
11        "http://petstore.com/1.png"
12      ],
13      "name": "doggie",
14      "isHealthy": true,
15      "tags": [
16        {
17          "id": 1,
18          "name": "狗狗"
19        }
20      ]
21    },
22    "quantity": 1,
23    "shipDate": "2019-08-26",
24    "status": "placed",
25    "completed": false
26  },
27  {
28    "id": 2,
29    "pet": {
30      "id": 1,
31      "category": {
32        "name": "金毛"
33      },
34      "status": "sold",
35      "photoUrls": [
36        "http://petstore.com/2.png"
37      ],
38      "name": "gucci",
39      "isHealthy": true,
40      "tags": [
41        {
42          "id": 1,
43          "name": "狗狗"
44        }
45      ]
46    },
47    "shipDate": "2019-12-26",
48    "status": "delivered",
49    "completed": true
50  }
51]

失败示例

参数有误

1{
2  "code": 2004,
3  "type": "ERROR",
4  "message": "status 不存在，必须为 placed, approevd, delivered 其中之一"
5}

查询订单

get/orders/{orderId}

请求 Request

路由参数

orderIdint
订单 ID

响应 Response

成功返回

状态码 200

参数

idint
订单 ID
petobject
Pet

宠物实体信息
- 子属性
- pet.idint
  ID
- pet.categoryobject必填
  Category
  
  宠物分类
  - 子属性
  - category.namestring必填
    名称
- pet.statusstring
  可选值：available , pending , sold
  |
  string
  状态
- pet.photoUrlsarray
  照片地址列表
  - 数组成员string
  - 照片地址
- pet.namestring
  名称
- pet.isHealthyboolean
  是否健康
- pet.tagsarray
  标签列表
  - 数组成员object
  - tags.idint
    ID
  - tags.namestring
    名称
shipDatestring
配送日期
statusstring
可选值：placed , approevd , delivered
|
string
订单状态
completedboolean
订单是否完成

错误返回 1

状态码 400

错误返回 2

点击展开

Example 1

请求示例

文本

get

{{BASE_URL}}/orders/3

成功示例

成功返回

1{
2  "id": 1,
3  "pet": {
4    "id": 1,
5    "category": {
6      "name": "金毛"
7    },
8    "status": "available",
9    "photoUrls": [
10      "http://petstore.com/1.png"
11    ],
12    "name": "doggie",
13    "isHealthy": true,
14    "tags": [
15      {
16        "id": 1,
17        "name": "狗狗"
18      }
19    ]
20  },
21  "shipDate": "2019-08-26",
22  "status": "placed",
23  "completed": false
24}

失败示例

删除宠物订单

delete/orders/{orderId}

请求 Request

路由参数

orderIdint
订单 ID

响应 Response

成功返回

状态码 200

参数

codeint
消息码
typestring
可选值：SUCCESS , ERROR
|
string
类型
messagestring
异常信息

错误返回 1

状态码 400

错误返回 2

点击展开

Example 1

请求示例

文本

delete

{{BASE_URL}}/orders/3

成功示例

删除成功

1{
2  "code": 0,
3  "type": "SUCCESS",
4  "message": ""
5}

失败示例

通过宠物 ID 查询订单

get/orders/getByPetId/{petId}

请求 Request

路由参数

petIdint
宠物 ID

响应 Response

成功返回

状态码 200

参数

idint
订单 ID
petobject
Pet

宠物实体信息
- 子属性
- pet.idint
  ID
- pet.categoryobject必填
  Category
  
  宠物分类
  - 子属性
  - category.namestring必填
    名称
- pet.statusstring
  可选值：available , pending , sold
  |
  string
  状态
- pet.photoUrlsarray
  照片地址列表
  - 数组成员string
  - 照片地址
- pet.namestring
  名称
- pet.isHealthyboolean
  是否健康
- pet.tagsarray
  标签列表
  - 数组成员object
  - tags.idint
    ID
  - tags.namestring
    名称
shipDatestring
配送日期
statusstring
可选值：placed , approevd , delivered
|
string
订单状态
completedboolean
订单是否完成

错误返回 1

状态码 400

错误返回 2

点击展开

Example 1

请求示例

文本

get

{{BASE_URL}}/orders/getByPetId/3

成功示例

成功返回

1{
2  "id": 1,
3  "pet": {
4    "id": 1,
5    "category": {
6      "name": "金毛"
7    },
8    "status": "available",
9    "photoUrls": [
10      "http://petstore.com/1.png"
11    ],
12    "name": "doggie",
13    "isHealthy": true,
14    "tags": [
15      {
16        "id": 1,
17        "name": "狗狗"
18      }
19    ]
20  },
21  "shipDate": "2019-08-26",
22  "status": "placed",
23  "completed": false
24}

失败示例

会话

关于用户的注册、登录和登出

Content-Typestring
可选值：application/json
|
默认值：application/json
|
string
媒体类型
X-RateLimit-Limitint
默认值：1000
接口调用次数限制（每小时）
X-Ratelimit-Retry-Afterstring
默认值：60
|
string
触达限流后需要等待重置的时间（秒）
X-RateLimit-Remainingint
默认值：1000
剩余可请求数量
X-Ratelimit-Resetint
默认值：600
重置限制次数时间（秒）

参数

codeint
消息码
typestring
可选值：SUCCESS , ERROR
|
string
类型
messagestring
异常信息

错误返回 1

状态码 400

HEADER

Content-Typestring
可选值：application/json
|
默认值：application/json
|
string
媒体类型

参数

codeint
消息码
typestring
可选值：SUCCESS , ERROR
|
string
类型
messagestring
异常信息

错误返回 2

点击展开

Example 1

成功示例

文本

post

{{BASE_URL}}/login

成功示例

登录成功

1{
2  "code": 2005,
3  "type": "ERROR",
4  "message": "password 必填"
5}

失败示例

登录失败

1{
2  "code": "3000",
3  "type": "ERROR",
4  "message": "用户名或密码错误"
5}

失败示例

参数有误

1{
2  "code": "3000",
3  "type": "ERROR",
4  "message": "用户名或密码错误"
5}

登出

用户登出

get/logout

响应 Response

状态码 200

参数

codeint
消息码
typestring
可选值：SUCCESS , ERROR
|
string
类型
messagestring
异常信息

Example 1

成功示例

登出成功

1{
2  "code": 0,
3  "type": "SUCCESS",
4  "message": "登出成功"
5}

用户注册

post/register

请求 Request

HEADER

Content-Typestring必填
可选值：application/json
|
string
媒体类型
Acceptstring必填
可选值：application/json
|
string
接受响应媒体类型

请求 BODY

usernamestring必填
用户名
passwordstring必填
密码
emailstring
EMAIL
mobilestring
手机号
sexstring必填
可选值：female , male
|
string
性别
ageint
年龄
agreeTermsboolean
统一条款

响应 Response

成功返回

状态码 200

HEADER

X-RateLimit-Limitint
默认值：1000
接口调用次数限制（每小时）
Content-Typestring
可选值：application/json
|
string
媒体类型
X-Ratelimit-Retry-Afterstring
默认值：60
|
string
触达限流后需要等待重置的时间（秒）
X-Ratelimit-Resetint
默认值：600
重置限制次数时间（秒）
X-RateLimit-Remainingint
默认值：1000
剩余可请求数量

参数

idint
用户 ID
usernamestring
用户名
emailstring
EMAIL
mobilestring
手机号
sexstring
性别
ageint
年龄

错误返回 1

状态码 400

参数

codeint
消息码
typestring
可选值：SUCCESS , ERROR
|
string
类型
messagestring
异常信息

错误返回 2

点击展开

错误返回 3

点击展开

Example 1

成功示例

文本

post

{{BASE_URL}}/register

成功示例

请求成功

1{
2  "id": 1,
3  "username": "coding",
4  "email": "support@coding.net",
5  "mobile": "13888888888",
6  "sex": "male",
7  "age": "18"
8}

失败示例

请求错误

1{
2  "code": "3001",
3  "type": "ERROR",
4  "message": "用户名已被占用，请更改后重新提交"
5}

失败示例

参数有误

1{
2  "code": "2005",
3  "type": "ERROR",
4  "message": "密码输入有误，仅支持大小写字母、数字以及 !@#$%^&*()_+-=~{}[]:;<>?/.,"
5}

失败示例

达到限流

1{
2  "code": "9999",
3  "type": "ERROR",
4  "message": "达到限流，请稍后再试"
5}

宠物商店 API 文档

调用说明

请求

参数传入方式

响应

认证

OAuth 流程

第 1 步 - 跳转用户授权

第 2 步 - 使用授权码（code）将用户重定向到您的应用服务器

第 3 步 - 使用授权码（code）交换访问令牌（Access Token）

第 4 步 - 使用访问令牌访问 API 资源

作用域 Scopes

请求限制

错误

状态码说明

业务错误说明

版本

字段类型

宠物

.css-wjdogd{-webkit-text-decoration:initial;text-decoration:initial;}宠物列表

QUERY

HEADER

参数

参数

Example 1

请求示例

成功示例

失败示例

新增宠物

请求 BODY

参数

Example 1

成功示例

成功示例

失败示例

宠物详情

HEADER

路由参数

HEADER

参数

Example 1

请求示例

成功示例

成功示例

失败示例

更新宠物信息

路由参数

请求 BODY

参数

Example 1

成功示例

成功示例

失败示例

路由参数

请求 BODY

参数

Example 1

成功示例

成功示例

失败示例

删除宠物

路由参数

参数

Example 1

请求示例

成功示例

失败示例

上传照片

HEADER

路由参数

请求 BODY

参数

Example 1

请求示例

成功示例

失败示例

使用 form-data 上传照片

HEADER

路由参数

请求 BODY

宠物列表