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

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

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

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

1. 快速开发框架
   专为加速 API 开发而设计，开发者只需少量配置即可发布高质量 API。

2. Swagger 集成
   用于在 IRIS 平台上开发 REST API 的规范和文档界面。基于开放式 API 规范（OAS）标准，支持 API 的使用、测试和执行。

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

开放式 API 规范（OAS）是全球通用的标准，用于定义、记录和使用 API：

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

三. 传统方式发布 IRIS API 的流程

使用传统方法构建并发布 REST API 通常需要：

1. 确定消费者调用路径、HTTP 动词及响应格式（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 提供详细的输入输出有效载荷属性记录，可让 Postman、Insomnia、Swagger 等工具快速与 API 集成。同时提供示例内容，便于轻松调用和测试 API。

六. API 定制化

通过在方法上定义特定符号，可更改路径名称或调整输入参数格式，补充方法本身未提供的元信息，从而提升最终用户体验。

七. 复杂类型支持与 API 投影图

框架支持复杂类型（对象）参数，这些对象将以 JSON 有效载荷公开，并在 OAS 中为每个属性正确记录。

八. 互操作性与复合 API

支持复杂类型后，可公开互操作性服务，非常适合构建复合 API（涉及多个外部组件编排）。
对象或消息可被 Swagger 等工具自动发布和读取，有助于测试和理解 API 属性。

九. 规范优先或 API 优先方法

API 开发中常用“先定义规范再实现”的方法。通过该框架，可导入 Open API 规范，自动生成方法结构，仅需补充实现部分。

十. API 管理与监控

建议结合 IAM（身份和访问管理）工具，实现 API 治理和权限管理。apiPub 提供额外的 API 跟踪功能，可快速集成 OAS 标准。

十一. 总结

通过 InterSystems Open Exchange 工具，开发者可以显著加速 API 的开发和部署过程。快速开发框架、Swagger 集成和 OAS 标准支持，使复杂 API 定制和互操作性实现更加简单高效。

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