rest怎么测试api（API文档中的五个常见部分）

几乎所有的API参考主题都包括以下五个部分：

1. 资源说明 “资源”是指API返回的信息。
2. 终点和方法 端点指示您如何访问资源，而方法指示与资源的允许的交互（例如GET，POST或DELETE）。
3. 参数 参数是您可以随端点传递的选项（例如，指定响应格式或返回的数量）以影响响应。
4. 请求示例 该请求示例包括一个使用端点的示例请求，其中显示了一些已配置的参数。
5. 响应示例和架构响应示例 显示了来自请求示例的示例响应。响应模式定义了响应中所有可能的元素。

目录

步骤1：资源说明

• 资源描述示例
• 描述资源的术语
• 认识参考文档与用户指南之间的区别

步骤2：端点和方法

• 端点示例
• 用花括号表示路径参数
• 您可以在端点旁边列出方法
• 端点仅显示结束路径
• 如何对同一资源的多个端点进行分组
• 如何在教程中引用端点

步骤3：参数

• 参数示例
• 四种参数
• 参数文档中的注意事项
• 标头参数
• 路径参数
• 查询字符串参数
• 请求正文参数

步骤4：请求示例

• 请求示例
• 多个请求示例
• 各种语言的请求
• 自动生成代码样本
• SDK为API提供工具
• API浏览器可与您自己的数据进行交互
• API Explorer在用户手中可能很危险

步骤5：响应示例和架构

• 响应示例和模式的示例
• 您需要定义响应吗？
• 在示例响应中使用实际值
• 格式化JSON并使用代码语法突出显示
• 记录嵌套对象的策略
• 三栏式设计
• 嵌入动态响应
• 那状态码呢？

步骤1：资源说明

“资源”是指API返回的信息。大多数API具有可以返回的各种类别的信息或各种资源。

资源描述简短（1-3个句子），通常以动词开头。资源通常具有各种端点来访问资源，并且每个端点都有多种方法。在同一页面上，通常会描述一个常规资源以及用于访问该资源的许多端点。

资源描述示例

这是Mailchimp API Campaigns资源中资源描述的示例：

Campaigns资源描述示例

‌通常，API将在同一资源下分组多个端点。在这种情况下，您将描述常规资源和各个端点。例如，Campaigns资源具有各种端点，这些端点也进行了描述：

Campaigns资源端点示例

这是Box API中的Membership资源的资源描述：

Box API资源示例

‌对于成员资格资源（或称其为“对象”），可以调用7种不同的端点或方法。Box API描述了成员资格资源以及使您可以访问该资源的每个端点。有时没有描述一般资源；相反，它只是将端点分组。大部分描述出现在每个端点中。例如，在Eventbrite API中，以下是“事件”资源：

Eventbrite API资源示例

‌尽管此处没有描述“事件”资源，但已为每个“事件”端点添加了描述。事件资源包含所有这些端点：

Eventbrite端点示例

‌作为另一个示例，Instagram API的先前版本描述了一个Relationships资源，如下所示：

Instagram API资源示例

没有描述“关系”资源，而是充当关系端点的容器。将为“关系”资源中分组的每个资源添加描述：

Instragram API 端点示例

‌有关具有资源和端点的API的另一个示例，请查看Trello API。

描述资源的术语

引用资源的确切术语有所不同。使用URL访问的“事物”可以通过多种方式引用，但是“资源”是最常见的术语，因为您是通过URL或统一资源定位符访问它们的。除了“资源”，您可能还会看到诸如API调用，端点，API方法，调用，对象，服务和请求之类的术语。一些文档通过不明确地调用除“参考”之外的任何内容来避免这种情况。

尽管术语多种多样，但通常API会通过“端点”访问各种“资源”。端点使您可以访问资源。（但是术语不是标准的，因此请多加注意。）

有关API术语如何变化的更多信息，请参见bunq API文档中的资源，端点，对象和项目之间的区别。

认识参考文档与用户指南之间的区别

资源描述（以及端点描述）通常很短，通常为1-3个句子。如果要添加更多详细信息怎么办？在这些情况下，请记住参考文档和用户指南/教程之间的区别：

• 参考文档：开发人员可以快速参考的简明信息。
• 用户指南/教程：有关如何使用API​​的详细说明，包括分步说明，代码示例，概念和过程。我将在“记录概念”部分中详细介绍此内容。

‌尽管API参考主题中的描述提供了该资源包含的信息的1-3个句子的摘要，但是您可以在用户指南中对此进行更详细的扩展。（您可以将参考描述链接到指南中提供更多详细信息的位置。）

步骤2：端点和方法

端点指示您如何访问资源，而方法指示与资源的允许的交互（例如GET，POST或DELETE）。

同一资源通常具有各种相关的端点，每个端点具有不同的路径和方法，但是返回有关同一资源的不同信息。端点通常具有简短的描述，类似于总体资源描述，但简短。此外，端点仅显示资源URL的结束路径，而不显示所有端点共有的基本路径。

1. 端点示例
2. 用花括号表示路径参数
3. 您可以在端点旁边列出方法
4. 端点仅显示结束路径
5. 如何对同一资源的多个端点进行分组
6. 如何在教程中引用端点

• ‌端点示例

这是Instagram API中Relationships资源的端点示例：

Instagram API端点示例

终结点通​​常以风格化的方式进行设置，使其更具视觉吸引力。许多文档都是围绕端点构建的，因此在文档中赋予每个端点更多的视觉效果可能是有意义的。

端点可以说是API文档最重要的方面，因为这是开发人员将用来实现其请求的内容。

用花括号表示路径参数

如果端点中具有路径参数，请使用花括号将其表示。例如，这是Mailchimp API的示例：

/campaigns/{campaign_id}/actions/send

如果可以，请将path参数设置为另一种颜色以将其突出：

/campaigns/{campaign_id}/actions/send

用户会理解，路径参数的花括号是一个惯例。在上面的示例中，几乎没有端点在实际路径语法中使用花括号，因此{campaign_id}是一个明显的占位符。

这是来自Facebook API的示例，该示例以一种易于识别的方式为path参数着色：

Facebook API path参数着色示例

当在Facebook的文档中描述参数时，使用相同的绿色来衬托参数，这有助于用户识别其含义。

路径参数并非总是以唯一的颜色设置（例如，某些颜色前面带有冒号），但是无论采用哪种约定，请确保可以轻松识别路径参数。

您可以在端点旁边列出方法

‌通常在端点旁边列出方法（GET，POST等）。该方法使用资源定义操作。简要地，每种方法如下：

• GET：检索资源
• POST：创建资源
• PUT：在现有资源中更新或创建
• PATCH：部分修改现有资源
• DELETE：删除资源有关

更多详细信息，请参见维基百科有关HTTP的文章中的请求方法。（还有一些其他方法，但很少使用。）由于方法本身没有太多要说的，因此将方法与端点归为一组是很有意义的。这是Box API的示例：

Box API的请求方法示例

这是Linkedin API的示例：

端点仅显示结束路径

描述端点时，仅列出端点路径（因此称为“端点”）。包含基本路径和端点的完整路径通常称为资源URL。

在我们的示例API场景中，端点仅为/ surfreport / {beachId}。您不必每次都列出完整的资源URL（即api.openweathermap/surfreport{beachId}）。包括完整的资源URL将分散用户对重点路径的注意力。在用户指南中，通常会在介绍性部分（例如“入门指南”）中说明完整的资源URL以及所需的授权。

如何对同一资源的多个端点进行分组

记录端点和方法时，另一个要考虑的问题是如何对端点进行分组和列出，特别是在您拥有大量相同资源的端点的情况下。在资源描述示例中，我们研究了各种API。许多文档网站为将资源的每个端点分组或列出都提供了不同的设计，因此，我不会重复所有相同的示例。以某种有意义的方式对端点进行分组，例如按方法或按返回的信息类型。

例如，假设您有三个GET端点和一个POST端点，所有这些端点都与同一资源相关。一些文档网站可能会在同一页面上列出同一资源的所有端点。其他人可能将它们分成单独的页面。其他人可能为GET端点创建一个组，为POST端点创建另一个组。这取决于您对每个端点要说多少。

如果端点几乎相同，则将它们合并在一个页面上可能很有意义。但是，如果它们实质上是唯一的（具有不同的响应，参数和错误消息），则将它们分隔到不同的页面可能会更好（并且更易于管理）。同样，通过更复杂的网站设计，您可以在同一页面上浏览冗长的信息。

如何在教程中引用端点

在教程和其他概念性内容中，如何在API参考主题中引用端点？提及“ / aqi endpoint”或“ / weatherdata”端点并没有多大区别。但是，对于更复杂的API，使用端点来谈论资源可能很棘手。

在我工作的一家公司中，我们用于Rewards端点的URL如下所示：

/rewards /rewards/{rewardId} /users/{userId}/rewards /users/{userId}/rewards/{rewardId}

任务中的奖励如下所示：、

/users/{userId}/rewards/{missionId} /missions/{missionid}/rewards

说您可以使用奖励资源并不总是那么具体，因为存在多个奖励和任务终点。

引用端点可能会很尴尬。例如，您可能会有这样的句子：“当您调用/ users / {userId} / rewards /时，您将获得所有奖励的列表。为了获得针对特定用户的特定任务的特定奖励，/ users / {userId} / rewards / {missionId}端点采用了几个参数……”

端点越长，参考就越麻烦。这些描述在文档的概念部分中更为常见。通常，对于如何引用繁琐的端点并没有明确的约定。采用最适合您的API的方法。

步骤3：参数

参数是您可以随端点传递的选项（例如，指定响应格式或返回的数量）以影响响应。参数有四种类型：标头参数，路径参数，查询字符串参数和请求正文参数。

通常在同一页面上的不同组中记录不同类型的参数。并非所有端点都包含每种类型的参数。

1. 参数示例
2. 四种参数
3. 参数文档中的注意事项
4. 标头参数
5. 路径参数
6. 查询字符串参数
7. 请求正文参数

参数示例

以下屏幕截图显示了Box API的示例参数部分：

Box API 参数示例

Box API的样本参数

‌在此示例中，参数按类型分组：路径参数，查询参数和主体参数。端点还以可识别的方式在端点定义中设置了路径参数（collab_id）。

‌很多时候，参数只是在表或定义列表中列出，如下所示：

Box API的样本参数示例

您可以通过多种方式（除了表格外）格式化值。如果您使用的是定义列表或其他非表格格式，请确保开发出易于读取的样式。

‌四种参数

REST API具有四种类型的参数：

• 标头参数：请求标头中包含的参数，通常与授权相关。
• 路径参数：端点路径中查询字符串（？）之前的参数。这些通常放在花括号内。
• 查询字符串参数：端点查询字符串中位于？之后的参数。
• 请求正文参数：请求正文中包含的参数。通常以JSON形式提交。

‌参数文档中的注意事项

无论参数类型如何，请为每个参数定义以下内容：

• 数据类型
• 最大值和最小值

‌参数的数据类型

‌如果数据类型或格式错误，API可能无法正确处理该参数。列出数据类型通常对于所有参数类型都是一个好主意，但对于请求主体参数尤其如此，因为这些参数通常以JSON格式设置。

‌这些数据类型是REST API最常见的类型：

• 字符串（string）：字母和/或数字的字母数字序列整数：
• 整数（integer）-可以是正数或负数
• 布尔值（boolean）：真或假值
• 对象（object）：JSON格式的键值对
• 数组（array）：值列表

‌参数的最大值和最小值

除了指定数据类型外，参数还应指示最大值，最小值和允许的值。例如，如果天气API仅允许特定国家/地区的经度和纬度坐标，则应在参数文档中描述这些限制。

忽略有关最大/最小值或其他不允许的值的信息是文档中的常见陷阱。开发人员常常没有意识到用户使用API​​的所有“创造性”方式。质量保证团队（QA）可能是识别不允许值的最佳资源，因为这是试图破坏API的质量保证。

‌

标头参数

‌标头参数包含在请求标头中。通常，标头仅包含所有端点都通用的授权参数；因此，标头参数通常不会记录在每个端点上。相反，标头参数中的授权详细信息记录在授权要求部分中。

‌但是，如果端点要求在标头中传递唯一的参数，则可以在每个端点的参数文档中记录它们。

‌路径参数

路径参数是端点本身的一部分，不是可选的。例如，在以下端点中，{user}和{bicycleId}是必需的路径参数：

/service/myresource/user/{user}/bicycles/{bicycleId}

‌路径参数通常用花括号引起来，但是某些API文档样式在该值之前加冒号或使用其他语法。在记录路径参数时，请指定默认值，允许值和其他详细信息。

‌对路径参数进行颜色编码

当您在端点中列出路径参数时，可以帮助对参数进行颜色编码，使其更易于识别。对参数进行颜色编码可以清楚地知道什么是路径参数，什么不是。通过颜色，可以在端点和参数定义之间创建直接连接。

‌例如，您可以对参数进行颜色编码，如下所示：

颜色编码示例额

然后，您可以在以后的描述中为这些参数使用相同的颜色：

颜色编码示例

通过对参数进行颜色编码，可以很容易地看到所定义的参数及其与端点定义的关系。

‌

查询字符串参数

查询字符串参数出现在端点中的问号（？）后面。参数和它们的值后面的问号称为“查询字符串”。在查询字符串中，每个参数都一个接一个地列出，并用＆分隔。查询字符串参数的顺序无关紧要。

例如：

查询字符串示例额

和

查询字符串示例

将返回相同的结果。但是，对于路径参数，顺序确实很重要。如果参数是实际端点的一部分（不在查询字符串后添加），则通常在端点本身的描述中描述此值。

‌

请求正文参数

通常，对于POST请求（在其中创建内容），您需要在请求正文中提交JSON对象。这称为请求正文参数，格式通常为JSON。此JSON对象可能是带有多层嵌套的键/值对的冗长列表。

例如，端点可能很简单，例如/ surfreport / {beachId}。但是在请求的主体中，您可能会包含一个具有许多键值对的JSON对象，如下所示：

请求正文参数示例

记录复杂的请求主体参数记录

‌JSON数据（包括请求正文参数和响应）是API文档中比较棘手的部分之一。如果对象很简单，并且在同一级别只有几个键/值对，则记录JSON对象很容易。但是，如果您有一个JSON对象，其中的对象内部有多个对象，许多层的嵌套以及冗长的条件数据，则可能会很棘手。而且，如果JSON对象跨越100行或1000行以上，则需要仔细考虑如何呈现信息。

‌表格可以很好地记录JSON，但是在表格中，很难区分顶级项目和子级项目。包含一个对象的对象也可能包含一个对象，另一个对象等可能会令人困惑。

‌无论如何，如果JSON对象相对较小，则表可能是您的最佳选择。但是设计师也采用了其他方法。

‌看看eBay的findItemsByProduct资源。这是请求正文参数（在这种情况下，格式为XML）：

eBay API正文参数示例

在请求正文参数下方是描述每个参数的表格：

参数表格示例

但是样本请求还包含指向每个参数的链接。在样本请求中单击参数值时，您会转到一个页面，该页面提供有关该参数值的更多详细信息，例如ItemFilter。由于参数值更复杂并且需要详细说明，因此可能会有单独的页面具有更多详细信息。

在其他请求中也可能使用相同的参数值，因此eBay的方法可能会促进重用。即使这样，我也不喜欢跳到其他页面来获取所需的信息。‌

1. Swagger UI的请求body参数的方法

Swagger UI（我们稍后将进行演示，并进行演示）提供了另一种记录请求正文参数的方法。Swagger UI以您在下面看到的格式显示请求正文参数。Swagger UI使您可以在响应和请求正文参数的“示例值”和“模型”视图之间切换。

Swagger UI的请求body参数示例

请参阅Swagger Petstore，在此处浏览演示。“示例值”显示了语法示例以及示例。单击“模型”链接时，您会看到一个示例请求正文参数以及每个元素的任何描述。

该模型包括带有值的展开/折叠开关。（Petstore演示在模型中并未包含许多参数描述，但如果包含描述，它们将显示在模型中而不是示例值中。）

您会发现在请求正文参数中记录JSON和XML的方式多种多样。没有正确的方式来记录信息。与往常一样，选择以最清晰，最易读的方式描述API参数的方法。

如果您的参数相对简单，那么选择就没有太大关系。但是，如果您有复杂，笨拙的参数，则可能必须诉诸自定义样式和模板才能更清晰地呈现它们。我将在“响应示例和模式”部分中更深入地探讨该主题。

步骤4：请求示例

该请求示例包括一个使用端点的示例请求，其中显示了一些已配置的参数。请求示例通常不会显示所有可能的参数配置，但是应尽可能丰富参数。

样本请求有时包含代码片段，这些代码片段以多种语言（除了curl之外）显示相同的请求。以其他编程语言显示的请求是可选的，并不总是包含在参考主题中（但是，如果可用，用户欢迎它们）。

• 请求示例
• 多个请求示例
• 各种语言的请求
• 自动生成代码样本
• SDK为API提供工具
• API浏览器可与您自己的数据进行交互
• API Explorer在用户手中可能很危险

请求示例

以下示例显示了来自Callfire API的示例请求：

Callfire API的示例请求

该API文档网站的设计将示例请求和响应安排在三列布局的右列中。该请求以curl格式设置，我们在前面的“进行curl调用”中进行了探讨。

curl -u "username:password" -H "Content-Type:application/json" -X GET "api.callfire/v2/texts?limit=50&offset=200"

curl是一种常见的显示请求的格式，其原因如下：

• curl与语言无关，因此它并不特定于一种特定的编程语言。
• curl显示请求中所需的标头信息。
• curl显示了与请求一起使用的方法。

‌通常，使用curl来显示您的样品请求。这是Parse API中的curl请求的另一个示例：

Parse API中的curl请求示例

您可以在curl中添加反斜杠以将每个参数分隔到自己的行中（尽管，正如我在curl教程中指出的那样，Windows在反斜杠方面遇到了麻烦）。

‌其他API文档站点可能会使用完整的资源URL，例如Twitter的以下简单示例：

Twitter API请求示例

资源URL包括基本路径和端点。显示完整资源URL的一个问题是，它不指示是否需要传递任何标头信息来授权请求​​。（如果您的API仅包含GET请求，并且不需要授权，那么很好，但是通过这种方式设置的API很少。）curl请求可以轻松显示任何标头参数。

‌多个请求示例

如果您有很多参数，请考虑包括几个请求示例。在CityGrid Places API中，where端点如下：

CityGrid Places API多个请求示例

但是，从字面上看，您可以使用17个可能的查询字符串参数。结果，该文档包含几个示例请求，这些请求显示了各种参数组合：

参数组合示例

当通常不一起使用参数时，添加多个请求示例很有意义。例如，在少数情况下，您实际上可能在同一请求中包括所有17个参数，因此任何示例在显示内容方面都会受到限制。

本示例说明如何“按字母顺序查找波士顿的酒店，查看结果1-5”：

api.citygridmedia/content/places/v2/search/where?what=hotels&where=boston,ma&page=1&rpp=5&sort=alpha&publisher=test&format=json

如果单击链接，则可以直接看到响应。在“响应”主题中，我将详细介绍如何在用户单击请求时动态显示响应。您应该显示多少个不同的请求和响应？可能没有简单的答案，但可能不超过几个。您决定什么对您的API有意义。举几个例子，用户通常会理解这种模式。

‌各种语言的请求

如前所述，在什么是REST API中，REST API与语言无关。通用协议有助于促进跨编程语言的广泛采用。开发人员可以使用任何语言编写应用程序，从Java到Ruby到JavaScript，Python，C＃，Node JS或其他任何语言。只要开发人员可以使用该语言发出HTTP Web请求，他们就可以使用该API。Web请求的响应将包含JSON或XML数据。

由于您无法完全了解最终用户将使用哪种语言进行开发，因此尝试提供每种语言的代码示例是徒劳的。许多API仅显示提交请求的格式和示例响应，并且作者将假定开发人员将知道如何以其特定的编程语言提交HTTP请求。

但是，某些API确实会以多种语言显示简单的请求。这是Twilio的一个例子：

Twilio多语言显示示例

您可以为示例请求选择所需的语言：C＃，curl，Java，Node.js，PHP，Python或Ruby。这是Clearbit API的另一个示例：

Clearbit API的多语言显示示例

您可以在Shell（curl），Ruby，Node或Python中查看请求。开发人员可以轻松地将所需的代码复制到他们的应用程序中，而不用弄清楚如何将curl请求转换为特定的编程语言。

‌提供通常通过标签显示的各种请求，有助于使您的API易于实现。如果您可以根据实际用户的登录个人资料自动用实际用户的API密钥填充API密钥，那就更好了。

‌但是，不要为如此混乱的代码示例所吓倒。一些API文档工具（例如Readme.io或SwaggerHub）可以自动生成这些代码示例，因为使用不同编程语言发出REST请求的模式遵循一个通用模板。

‌自动生成代码样本

如果您不使用自动生成代码示例的创作工具，并且想要提供这些代码段，则可以根据需要从Postman和Paw中自动生成代码示例。

Paw（适用于Mac）可让您将请求导出为几乎所有可能的语言：

Paw多语言转换示例

配置请求后（类似于Postman的过程），可以通过转到文件>导出请求来生成代码段。Postman应用程序也可以类似的方式生成代码片段。我在之前的有关从响应有效内容中检查JSON的教程中介绍了此过程。在Postman中，配置请求后，单击“代码”链接（该链接显示在右上方区域中“保存”按钮的下方）。

Postman代码转换示例

然后选择所需的语言，例如JavaScript> Jquery AJAX：

Postman代码转换示例

（有关涉及使用Postman生成的jQuery代码的活动，请参阅从响应有效内容中检查JSON，然后访问Access并打印特定的JSON值。）

‌SDK为API提供工具

很多时候，开发人员会创建一个REST API附带的SDK（软件开发套件）。SDK可帮助开发人员使用特定工具来实现API。尽管API与语言无关，但SDK特定于语言。

例如，在我工作的一家公司中，我们同时拥有REST API和JavaScript SDK。由于JavaScript是开发人员使用的目标语言，因此该公司开发了JavaScript SDK，使使用JavaScript的REST更加容易。您可以通过JavaScript SDK提交REST调用，并传递许多与Web设计人员相关的参数。

SDK是可以简化使用API​​的任何一种工具。对于一家公司来说，提供一种与语言无关的REST API，然后开发一个SDK，可以轻松地以他们希望用户以其实现API的主要语言来实现该API，这是极为普遍的。其他语言的小请求摘要并不重要，因为SDK提供了更简单的实现。如果您有SDK，则需要制作更详细的代码示例，以显示如何使用SDK。

‌API浏览器可与您自己的数据进行交互

‌许多API都具有API资源管理器功能，该功能使用户可以直接从文档中发出实际请求。例如，这是Spotify API文档的典型参考页：

Spotify API文档的典型参考页

Flickr的API文档还具有内置的API资源管理器：

Flickr的API文档

和《纽约时报》 API一样：

《纽约时报》 API

通过API Explorer，您可以将自己的值，自己的API密钥和其他参数插入请求中，以便直接在API Explorer中查看响应。能够看到您自己的数据使响应更加真实和即时。

但是，如果您的系统中没有正确的数据，则使用您自己的API密钥可能无法向您显示完整的响应。当资源涉及公共信息并且请求是GET请求时，它效果最佳。

API Explorer在用户手中可能很危险

尽管交互功能很强大，但是API资源管理器可能会危险地添加到您的站点中。如果尝试DELETE方法的新手意外删除数据该怎么办？以后如何删除通过POST或PUT方法添加的测试数据？

允许使用GET方法是一回事，但是如果您包含其他方法，则用户可能会无意中破坏其数据。在Sendgrid的API中，在使用其API Explorer测试呼叫之前，它们会向用户发送警告消息：

Sendgrid的API Explorer示例

Foursquare的API文档以前在其文档的先前版本中具有内置的API资源管理器（如下所示），但此后已将其删除。我不确定为什么-也许他们遇到了其中一些问题。

就集成自定义API Explorer工具而言，对于开发人员而言，这是一项相对容易的任务。API Explorer所做的只是将字段中的值映射到API调用，并将响应返回到同一接口。换句话说，API管道就在那里—您只需要一些JavaScript和前端技能就可以实现它。但是，您不必构建自己的工具。诸如Swagger UI（用于分析OpenAPI规范文档）和Readme.io（允许您手动或从OpenAPI规范输入详细信息）之类的现有工具可以将API Explorer功能直接集成到文档中。

步骤5：响应示例和架构

响应示例显示了来自请求示例的示例响应。响应模式定义了响应中所有可能的元素。响应示例并不全面涵盖所有参数配置或操作，但应与请求示例中传递的参数相对应。响应使开发人员知道资源是否包含他们想要的信息，格式以及该信息的结构和标记方式。

响应的描述称为响应模式。响应模式以更全面，更通用的方式记录响应，列出可能返回的每个属性，每个属性包含的内容，值的数据格式，结构以及其他详细信息。

• 响应示例和模式的示例
• 您需要定义响应吗？
• 在示例响应中使用实际值
• 格式化JSON并使用代码语法突出显示
• 记录嵌套对象的策略
• 三栏式设计
• 嵌入动态响应
• 那状态码呢？

‌响应示例和模式的示例

‌以下是来自SendGrid API的示例响应。他们的文档提供了一个选项卡式显示，其中一个选项卡上有一个示例：

另一个选项卡上的响应模式：

响应的定义称为模式或模型（术语同义使用），并且与JSON模式语言和描述保持一致。与SendGrid示例一起特别有效的方法是使用expand / collapse标签来镜像与示例相同的结构，并且对象处于不同的级别。

‌Swagger UI还提供了示例值和架构或模型。例如，在我用于SwaggerUI活动的示例Sunrise和Sunset Times API文档中（本课程的后面部分），您可以看到响应示例和响应模式之间的区别。这是示例值：

示例响应应与示例请求相对应。正如请求示例可能只包括所有可能参数的子集一样，响应示例也可能是所有可能返回信息的子集。

‌但是，响应模式包含响应中返回的所有可能的属性。这就是为什么同时需要一个响应示例和一个响应模式的原因。这是Sunrise和Sunset Times API的响应架构：

模式或模型提供以下内容：

• 每个属性的描述
• 每个属性的数据类型的定义
• 每个属性是必需的还是可选的

如果标头信息对于包含在响应示例中很重要（因为它提供了标准状态代码以外的唯一信息），则也可以包含它。

‌您需要定义响应吗？

一些API文档省略了响应模式，因为响应可能看起来不言而喻或直观。在Twitter的API中，没有说明响应（您可以在此处查看示例）。

但是，使用描述的响应，大多数文档会更好，特别是如果属性是缩写或含糊的。开发人员有时会通过减少发送的文本量来简化响应以提高性能。在我记录的一个端点中，响应包括大约20个不同的两个字母的缩写。我花了几天时间追踪每个缩写的含义，发现许多使用该API的开发人员甚至都不知道许多响应的含义。

‌

在示例响应中使用实际值

在示例响应中，值应该是真实的而不是被真实的。如果开发人员给您提供了示例答复，请确保这些值合理且不会伪造成他们会分散注意力（例如，由漫画人物名称组成的用户）。

此外，样本响应中不应包含真实的客户数据。如果您从工程师那里得到了样本答复，并且数据看起来真实，请确保它不仅来自克隆的生产数据库，而且通常是这样做的。开发人员可能没有意识到数据必须是虚构的但具有代表性，因此抓取生产数据库可能是最简单的方法。

‌

格式化JSON并使用代码语法突出显示

‌对响应使用正确的JSON格式。JSON Formatter和Validator之类的工具可以确保间距正确。

‌如果您还可以添加语法突出显示，则一定要这样做。如果您在GitHub上使用静态网站生成器（例如Jekyll或markdown语法），则可能可以使用Rouge内置语法突出显示器。其他静态站点生成器可能使用Pygments或类似的扩展名。

‌Rouge和Pygments依靠“词法分析器”来指示应如何突出显示代码。例如，一些常见的词法分析器是java，json，html，xml，cpp，dotnet和javascript。

‌如果您没有任何语法突出显示工具可以直接集成到创作工具中，则可以使用在线语法突出显示工具，例如tohtml/jScript/。但是，将代码手动粘贴到这些编辑器中将是乏味的，并且可能是不可持续的。

‌记录嵌套对象的策略

‌很多时候，响应包含嵌套的对象（对象内的对象）或具有重复元素。格式化响应模式的文档是API参考文档更具挑战性的方面之一。

‌表格是最常用的。在Peter Gruenbaum关于Udemy的API技术写作课程中，Gruenbaum使用具有不同列的表来表示嵌套对象：

Gruenbaum使用表格主要是为了减少对工具的重视，并将其更多地放在内容上。Dropbox API用斜杠表示嵌套。例如，name_details /，team /和quota_info指示多个对象级别。

‌其他API将嵌套响应定义以模仿JSON结构。这是来自bit.ly API的示例：

多层次的结构通常让人望而却步，但在这里，它的目的是在不需要复杂样式的情况下很好地工作。

‌eBay的方法更具独特性。在这种情况下，MinimumAdvertisedPrice嵌套在DiscountPriceInfo内，DiscountPriceInfo嵌套在Item中，Item嵌套在ItemArray中。（另请注意，此响应使用XML而不是JSON）。

以下是响应文档：

同样有趣的是，eBay为每个商品包含了多少细节。Twitter的作者似乎省略了描述，而eBay的作者则写了一些小小说来描述回应中的每个项目。

‌三栏式设计

‌一些API将响应放在右列，因此您可以在查看响应的同时查看资源描述和参数。Stripe的API使这种三列设计广受欢迎：

Stripe的设计将示例响应并置在右侧窗格中，并将响应模式显示在主窗口中。想法是您可以同时看到两者。描述不一定总是与响应一致，这可能会造成混淆。不过，将响应示例与响应模式分开放在不同的列中有助于区分两者。

许多API都按照Stripe的设计建模。例如，请参阅“Slate”或“Spectacle”。您应该在API文档中使用三列布局吗？也许。但是，如果响应示例和说明未排成一行，则观看者的注意力将有所分散，并且用户必须诉诸于更多的上下滚动。另外，如果您的布局使用三列，则中间列将有一些狭窄的限制，不会为屏幕截图和代码示例留出太多空间。‌

MYOB开发人员中心采用了一种有趣的方法来记录其API中的JSON。他们以类似于表格的方式列出JSON结构，并具有不同的缩进级别。您可以将鼠标移到工具提示说明的字段上，也可以单击它以在下面展开说明。使用工具提示可使包含示例和说明的行完美对齐。

JSON定义的右侧是带有实数值的代码示例。选择一个值时，表中的元素和代码示例中的元素都同时突出显示。

这种方法有助于扫描，而popover 可折叠方法使您可以压缩表，从而可以跳到感兴趣的部分。但是，从文档角度来看，这种方法需要更多的手动工作。不过，如果您有很长的JSON对象，那可能是值得的。

嵌入动态响应

‌有时，响应是根据对测试系统的API调用动态生成的。或者，如果不是动态生成的，则它们似乎是动态的。例如，查看OpenWeatherMap API（我们在先前的活动中使用过）。当您单击“ API调用示例”部分中的链接（例如samples.openweathermap/data/2.5/weather?q=London）时，您会在浏览器中看到返回的响应。

‌实际上，OpenWeatherMap响应不是动态生成的，而是以这种方式生成的。

‌对于返回公共信息的GET请求，此动态方法效果很好。但是，它可能无法扩展为其他方法（例如POST或DELETE）或请求授权的方法。

‌

那状态码呢？

‌响应部分有时会简要列出响应返回的可能状态和错误代码。但是，由于这些代码通常是在API中的所有端点之间共享的，因此除了特定端点的文档外，状态和错误代码通常都记录在其自己的部分中。因此，我在记录状态和错误代码中介绍了此主题。

,