在 InterSystems IRIS 中使用 Swagger 构建高效 REST API：生成、预览与测试指南

一. 引言

在构建REST API 时，Swagger 是一个非常有用的工具，它不仅帮助开发者生成 API 文档，还能提供交互式测试功能。本文将介绍如何在 InterSystems IRIS 中使用 Swagger 构建 REST API，并展示实际操作和示例。

二. 使用 %REST.API 类生成 Swagger 文件

在 InterSystems IRIS 中，%REST.API 类是创建 Swagger 文件的基础。通过调用 GetWebRESTApplication 方法，可以生成 API 的 Swagger 定义文件。

具体文档可参考：InterSystems IRIS 文档

三. 发布 API 并访问文档工具

首先，需要发布 API。以下是示例 API 链接：

• 示例 API

通过访问 InterSystems IRIS 文档页面，可以使用工具将 API 调用输出转换为用户友好的界面，便于服务文档化和测试：

• 文档工具链接

四. Swagger 定义文件的结构

Swagger 定义文件本质上是 JSON 格式，在 InterSystems IRIS 中以 %DynamicObject 形式提供。通过 GetWebRESTApplication 方法，可以获取基于 OpenAPI 2.0 规范的定义文件。

1. 丰富 API 基本信息

根据 OpenAPI 2.0 规范，可以在 Swagger 定义中添加或删除信息，以丰富 API 的基本信息，例如标题、描述和版本等。

以下是示例定义截图：

五. 预览 Swagger 文档

在预览页面上调用 Swagger 文档时，可以看到以下输出：

通过文档页面，可以查看 API 的具体方法，例如：

• POST 方法：用于添加客户端
• GET 方法：用于检索列表

相关截图示例：

六. 测试 API 调用

Swagger 文档页面提供 “试试看” 功能，允许直接执行 API 调用并查看结果：

七. Code-first 方法的优势

使用 REST API 的 Code-first 方法，开发者可以灵活控制 API 文档内容，根据实际需求添加或删除信息，确保发布的文档内容精准且实用。

八. 总结

本文介绍了如何在 InterSystems IRIS 中使用 Swagger 构建 REST API，包括：

• 生成 Swagger 文件
• 发布和访问文档工具
• 丰富 API 基本信息
• 预览和测试 API 文档

通过这些步骤，开发者可以高效管理 REST API，提升文档可用性和开发效率。

原文链接：https://community.intersystems.com/post/rest-api-swagger-intersystems-iris