使用 Swagger 规范添加不可用的端点

Composer 中的 ThingWorx 模型定义 > 建模 > 集成连接器 > 集成连接器先决条件 > 使用 OData 连接器或 SAPOData 连接器 > 使用 Swagger 规范添加不可用的端点

例如，考虑 OData 规范中的以下 EntityType 定义：

允许添加 PrimaryContent 至指定 Document 的端点不包括在 ODataConnector 从解析 OData 规范生成的端点列表中。通常，由后端系统按照 EntityType 的 NavigationProperty 定义所支持的端点不包括在连接器生成的列表中。因此，您应当创建一个定义这些端点的 Swagger 规范，然后将该规范以 JSON 格式添加为 SwaggerJSON 属性的值。有关详细信息，请参阅使用 ODataConnector 或 SAPODataConnector。

对于上面的示例，我们可以通过阅读 OData 规范了解以下内容：

• 端点路径的格式为 /Documents('{ID}')/PrimaryContent，其中

◦ Documents 是 entitySet 的名称，后者包含 Document 实体。

◦ ID 是 Document 的 Key，用于唯一标识 Document 实例。围绕 ID 的括号 {} 表示它是必需路径参数的占位符，在请求用实际值替换占位符时必须提供该参数。

◦ PrimaryContent 是 Document 的 NavigationProperty。

• PUT 是 HTTP 操作，用于支持上载 Document 的 PrimaryContent，因为 PrimaryContent 是 ContentItem 类型。ContentItem 的 HasStream 特性设置为 True。

• 作为 Document 的 PrimaryContent 上载的文件是必需的输入，请求的 ContentType 应当是 multipart/form-data 才能确保请求执行成功。

• 执行端点的响应将是以下内容之一：

◦ 架构符合 ContentItem 定义的 JSON 对象。

◦ 指示请求无效的错误。

对端点执行请求的所有需求都应当使用应用程序 (例如 Google Chrome 扩展 Postman) 进行评估，然后再为其创建一个 Swagger 规范定义。

在 Postman 中评估需求之后，使用一个工具 (如 Swagger Editor) 创建端点的定义。

1. 使用空白 paths 对象启动编辑器。

2. 为端点添加路径，并添加路径支持的 HTTP 操作。在上例中，分别为 "/Documents('{ID}')/PrimaryContent" 和 put。

3. 添加 ID (path 参数) 和 File (formData 参数) 的输入参数定义。

4. 请将以下逻辑添加到端点：consumes: [ multipart/form-data ], 和 produces: [ application/json ]。

5. 添加端点生成的由 HTTP 状态码标识的响应。

例如：

◦ 成功的操作 (HTTP 状态码 200) 将返回一个 JSON 对象，其架构符合 ContentItem 定义。对 ContentItem 定义的引用由 $ref 属性指示。

◦ 无效请求 (HTTP 状态码 405)。

6. 添加 ContentItem 定义。请参阅 OData 规范中的 ContentItem entityType 定义以了解架构。

7. 为 PUT 操作提供 operationId 和 summary。

8. 在解决了编辑器中报告的错误并添加所需路径、操作和定义后，将 Swagger 规范导出为 JSON 文件。

9. 复制导出的 JSON 文件的内容，并将其设置为 SwaggerJSON 属性的值。