资源描述简短（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的结束路径，而不显示所有端点共有的基本路径。
端点示例用花括号表示路径参数您可以在端点阁下列出方法端点仅显示结束路径如何对同一资源的多个端点进行分组如何在教程中引用端点端点示例这是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（即https://api.openweathermap.org/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：参数参数是您可以随端点通报的选项（例如，指定相应格式或返回的数量）以影响相应。参数有四种类型：标头参数，路径参数，查询字符串参数和要求正文参数。
常日在同一页面上的不同组中记录不同类型的参数。并非所有端点都包含每种类型的参数。
参数示例四种参数参数文档中的把稳事变标头参数路径参数查询字符串参数要求正文参数参数示例
以下屏幕截图显示了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的方法可能会促进重用。纵然这样，我也不喜好跳到其他页面来获取所需的信息。
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 "https://api.callfire.com/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”：
https://api.citygridmedia.com/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.com/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调用示例”部分中的链接（例如http://samples.openweathermap.org/data/2.5/weather?q=London）时，您会在浏览器中看到返回的相应。
实际上，OpenWeatherMap相应不是动态天生的，而因此这种办法天生的。
对付返回公共信息的GET要求，此动态方法效果很好。但是，它可能无法扩展为其他方法（例如POST或DELETE）或要求授权的方法。
那状态码呢？
相应部分有时会简要列出相应返回的可能状态和缺点代码。但是，由于这些代码常日是在API中的所有端点之间共享的，因此除了特定端点的文档外，状态和缺点代码常日都记录在其自己的部分中。因此，我在记录状态和缺点代码中先容了此主题。
