向我们全新的Smartsheet API文档问好!今天，我们非常激动地宣布，我们正在更新我们的API文档，并使用行业标准呈现新的外观和感觉，OpenAPI．新的文档具有交互特性，例如完整的对象建模，可以展开或折叠以进行详细的工作，每个代码示例都有一个“Copy”按钮，更多的信息排成一行，而不是强迫您跳到不同的部分。

说得够多了，让我们给你看一些吧!

图1:一些新特性的标注。

当我们开始这个项目时，我们知道我们想要一个既能处理外部面向客户的功能又能处理内部开发速度的工具。对我们来说，在参考资料部分保持同样高水平的信息也是很重要的。我们利用这个机会研究了最佳实践、新工具和新技术，最终选择了OpenAPI，主要是因为OpenAPI使用API定义自动生成文档和模拟测试。它还允许像您这样的读者通过代码示例和改进的可读性获得交互式和沉浸式体验。

虽然文档包含相同的基本信息:一个REST端点和使用JSON格式的参数，在右侧窗格中有代码示例，但使用文档的体验是完全不同的。如果您想查看一个对象是如何在另一个对象中建模的，可以通过单击中间窗格中的“>”(大于符号)或示例代码中的“+”(加号符号)来对齐信息。

这样，每个对象、每个参数和每个响应都已经用JSON为您建模了。您还可以试验使用包含或排除查询参数时负载的变化。您不再需要猜测JSON对象的样子。

要查看新文档，请使用以下链接:Smartsheet API参考(2.0.0)．

当你需要时完成对象建模

因为每个对象都是建模的，我们的文档允许你压缩或展开对象(默认是压缩的)。在图2中，左侧圈出的图像包含一个值，旁边有一个“>”(大于符号)，表示这里有一个嵌入的对象。使用旧的文档格式，您必须通过链接到API文档中的另一个位置来查看该对象定义。有了新的文档，您可以通过单击“>”(大于符号，在这里显示在“reports”的右侧)来按行展开对象定义。图2的右边图像显示了展开的对象定义，箭头现在是向下的(v)。要再次压缩它，请单击向下的箭头。

图2:表中嵌入对象的示例。

以同样的方式，右窗格上的代码示例最初被折叠，以向您提供所选语言的概述(图3中的左图)。如果您想查看更多细节，请单击示例中圈出的“+”(加号)。图3的右图像显示了该对象现在是如何展开的。您可以单击“-”(负号)重新折叠该对象，也可以在每个代码示例的顶部使用“全部展开”或“全部折叠”切换。

图3:代码示例窗格中的嵌入对象示例。

告诉我们你的想法

我们计划对这些新文档进行迭代并不断改进。例如，我们的工程团队可以更明确地说明每个端点的典型错误代码是什么，或者我们可以构建更完整的SDK代码样本。

也许还有一些东西对你来说不是很有意义，或者你想了解更多细节?告诉我们你的想法!

我们喜欢听取客户的意见，想知道你们正在构建什么，你们正在努力解决什么问题，以及你们是否有功能要求，而我们目前的API还不能实现这些功能。使用此链接获取任何类型的反馈:API和开发者- Smartsheet社区

为了帮助您过渡到新的文档结构，旧的文档已弃用，但仍然可用。只要记住，Smartsheet将不再更新这些文档。你可能想要收藏新医生不过位置!