使用 InterSystems Open Exchange 工具进行快速 API 开发

在本文中，我们将分享在2023年全球峰会技术交流室中提出的主题，重点讨论如何使用 InterSystems Open Exchange 工具快速开发 API。以下内容将详细介绍相关工具和方法。

用于快速开发 API 的 Open Exchange 工具

在现代 API 的快速开发（如 REST/JSON）中，InterSystems Open Exchange 提供了两个重要工具：

1. **API 开发而设计，本文将对此进行详细介绍。
2. **开发 REST API 的规范和文档界面。其基于开放式 API 规范（OAS）标准，支持 API 的使用和执行。

什么是开放式 API 规范（OAS）？

开放式 API 规范（OAS）是一个全球通用的标准，用于定义、记录和使用 API。在大多数情况下，API 的设计甚至早于其实现。这种规范的重要性体现在以下几个方面：

• 定义并记录 REST API，便于提供者和使用者使用。
• 加速市场上工具（如 Swagger、Postman、Insomnia 等）中的测试和 API 调用。

使用 IRIS 发布 API 的传统方式

以下是通过传统方式从现有 IRIS 方法构建并发布 REST API 的流程：

1. 确定消费者调用 API 的路径、动词及响应格式（如 JSON 对象或纯文本）。
2. 在 %CSP 中构建新方法，由 REST 类处理 HTTP 请求。
3. 确保方法返回符合预期的 HTTP 响应。
4. 处理成功代码及异常情况。
5. 为新方法绘制路线图。
6. 手动构建 API 文档（OAS 内容）。
7. 如果涉及请求或响应有效载荷（对象），需额外记录 OAS 内容，增加实现时间。

使用快速开发框架的优势

通过简单地为 IRIS 方法添加 [WebMethod] 属性，框架将基于 OAS 3.x 标准自动处理 API 的发布。

为什么选择 OAS 3.x 标准？

OAS 3.x 标准不仅详细记录了输入和输出有效载荷的所有属性，还能让市场上的任何 REST 客户端工具（如 Insomnia、Postman、Swagger 等）快速与 API 集成。此外，它还提供示例内容，便于轻松调用和测试 API。

API 定制

如果需要自定义 API，例如更改路径名称或调整输入参数的格式，可以通过在方法上定义特定的符号，补充方法本身未提供的元信息。

在上述示例中，我们为 API 定义了更友好的路径和补充信息，从而提升最终用户体验。

复杂类型支持与 API 投影图

该框架支持多种类型的参数，包括复杂类型（对象）。这些复杂类型将自动以 JSON 有效载荷的形式公开，并通过 OAS 为每个属性正确记录。

互操作性与复合 API

通过支持复杂类型，该框架还可以公开互操作性服务。这对于构建复合 API（涉及多个外部组件的编排）非常有利。

例如，用作请求或响应的对象或消息将被工具（如 Swagger）自动发布和读取。这种方式不仅便于测试互操作性组件，还能通过加载有效载荷模板帮助用户了解 API 的属性。

规范优先或 API 优先方法

如今，API 开发中广泛采用的一个概念是：在实现 API 之前先定义其规范。通过此框架，可以导入 Open API 规范，自动生成方法结构，仅需补充实现部分。

API 管理与监控

为了实现 身份和访问管理）工具使用。IAM 提供了多个插件，并能通过 OAS 标准快速与 API 集成。此外，apiPub 提供了额外的 API 跟踪功能。

总结

通过 InterSystems Open Exchange 工具，开发者可以显著加速 API 的开发和部署过程。无论是快速开发框架、Swagger 集成，还是 OAS 标准的支持，这些工具都为现代 API 开发提供了强大的支持。同时，框架的灵活性和扩展性也让开发者能够轻松应对复杂的定制化需求。

原文链接: https://community.intersystems.com/post/fast-api-development-using-intersystems-open-exchange-tools