文章 cheng yu · 1 小时前 6m read

OpenAPI 规范的生成

#InterSystems IRIS #JSON #ObjectScript #REST API #教程

引言

REST API（表征状态转移）是一种接口，它允许不同的应用程序通过HTTP协议，利用GET、POST、PUT和DELETE等标准操作进行相互通信。REST API在软件开发中被广泛应用，用于提供可供其他应用程序访问的服务，从而实现不同系统之间的集成。

然而，为了确保 API 易于理解和使用，完善的文档至关重要。这就是 OpenAPI 发挥作用的地方。

OpenAPI 是一种用于描述 RESTful API 的标准。它允许以结构化的方式定义 API 的功能，包括指定可用的端点、接受和返回的数据类型、必需的参数以及预期的响应。所有这些信息都汇总在一个规范文件中（通常扩展名为 .yaml 或 .json），自动化工具可以解析该文件以生成代码、文档等内容。

OpenAPI 规范旨在同时满足机器和人类的可读性，从而以标准化方式实现 RESTful Web 服务的描述、生成、使用和可视化。因此，OpenAPI 文档代表了对 API 的正式描述，既有助于需要使用该API 的开发者，也便于相关工具利用它来自动化各种流程。

定义规范文件有什么用处？

采用 OpenAPI 来记录 API 具有以下几个好处：

清晰度：它提供了详细且结构化的文档，使开发人员能够快速了解如何与 API 交互、应发送哪些请求以及响应中会包含哪些数据。
自动化：文档可从代码中自动生成，并能随着 API 的任何变更而保持最新。
交互性：诸如Swagger（一套用于 API 文档编写和测试的开源工具套件）等工具包含Swagger UI。这使您能够直接在浏览器中探索和测试 API，从而简化 API 的开发、验证和理解过程。
标准化：使用 OpenAPI 可确保文档遵循通用且被广泛认可的格式，从而促进与其他工具及服务的集成。

如何生成 OpenAPI 文档？

生成 OpenAPI 规范文件主要有两种方法：

“代码优先”（自动）方法：如果已在 InterSystems IRIS 中开发了 REST API，则无需手动编写规范文件，即可自动生成 OpenAPI 文档。IRIS 提供了一项集成功能，可根据 REST 类定义将 OpenAPI 文档导出为 JSON 或 YAML 格式。
“规范优先”（手动）方法：在此情况下，需手动编写 YAML 或 JSON 格式的 OpenAPI 文件，其中描述了所有端点、参数和预期响应。当您希望在实现 API 之前先对其进行定义时，此方法非常有用，有助于设计工作，并便于与其他开发人员或利益相关者共享。

自动方法

在 InterSystems IRIS 中，有两种方法可以自动生成 OpenAPI 规范文件。

方法 1：使用 `GetWebRESTApplication` 函数

一种方法是使用 %REST.API 类提供的GetWebRESTApplication函数。
一个实际的使用示例是在分派类中添加以下函数：

ClassMethod GenerateOpenAPI() As %Status
{
    // The name of the REST application
    Set webApplication = "MyAPP"  // Replace with the name of your web app
    // Retrieve the OpenAPI 2.0 documentation
    Set sc = ##class(%REST.API).GetWebRESTApplication("", webApplication, .swagger)
    
    If $$$ISERR(sc) {
        Quit sc  // If an error occurred, exit the method
    }
    
    // Return the documentation in JSON format
    Set %response.ContentType = "application/json"
    Do ##class(OMRREST.impl).%WriteResponse(swagger.%ToJSON()) 

    Quit $$$OK
}

此外，请在UrlMap 中添加以下路由：

  <Route Url="/openapi" Method="GET" Call="GenerateOpenAPI"/>

至此，您已具备从分发类生成规范文件所需的一切条件。要查看文档，请访问以下 URL（其中 MyWebapp 是您在管理门户中定义的 Web 应用程序名称）：

<host>:<port>/MyWebapp/openapi

通过此方式生成的 JSON 代表了您 API 的 OpenAPI 规范。在探讨第二种方法之后，我们将了解如何在 Swagger 中查看和测试该规范。

方法 2：使用管理 API

生成 OpenAPI 规范文件的另一种方法是使用InterSystems IRIS 管理 API。

要调用此服务，您可以使用Postman 等工具，这是一款允许您测试、文档化和自动化 API 的开发工具。
Postman 提供了一个简单直观的界面，用于发送 HTTP 请求（GET、POST、PUT、DELETE 等）、查看响应、管理身份验证以及创建自动化测试。

若要使用 Postman 发送请求，请按照以下步骤操作：

点击 New 按钮并创建一个 HTTP 请求。
按以下方式配置请求并发送：
- 选择GET作为 HTTP 方法。
- 按以下格式指定 URL，其中请使用您实例的 <baseURL>：
```
https://<baseURL>/api/mgmnt/v1/namespace/myapp
```
  此处，namespace 是您创建 REST 服务的命名空间名称，myapp 是您的 Web 应用程序名称。
- 将“授权”方法设置为“基本认证”，并提供具有指定命名空间读取权限的用户名和密码。

生成 JSON 后，可使用Swagger Editor 等工具进行查看和测试。

{
   "info":{
      "title":"",
      "description":"",
      "version":"",
      "x-ISC_Namespace":"MyNamespace"
   },
   "basePath":"/MyWebapp",
   "paths":{
      "/loginForm":{
         "post":{
            "parameters":[
               {
                  "name":"payloadBody",
                  "in":"body",
                  "description":"Request body contents",
                  "required":false,
                  "schema":{
                     "type":"string"
                  }
               }
            ],
            "operationId":"loginForm",
            "x-ISC_ServiceMethod":"loginForm",
            "responses":{
               "default":{
                  "description":"(Unexpected Error)"
               },
               "200":{
                  "description":"(Expected Result)"
               }
            }
         }
      },
      "/refresh":{
         "post":{
            "parameters":[
               {
                  "name":"payloadBody",
                  "in":"body",
                  "description":"Request body contents",
                  "required":false,
                  "schema":{
                     "type":"string"
                  }
               }
            ],
            "operationId":"refresh",
            "x-ISC_ServiceMethod":"refresh",
            "responses":{
               "default":{
                  "description":"(Unexpected Error)"
               },
               "200":{
                  "description":"(Expected Result)"
               }
            }
         }
      },
      "/logout":{
         "post":{
            "parameters":[
               {
                  "name":"payloadBody",
                  "in":"body",
                  "description":"Request body contents",
                  "required":false,
                  "schema":{
                     "type":"string"
                  }
               }
            ],
            "operationId":"logout",
            "x-ISC_ServiceMethod":"logout",
            "responses":{
               "default":{
                  "description":"(Unexpected Error)"
               },
               "200":{
                  "description":"(Expected Result)"
               }
            }
         }
      },
      "/openapi":{
         "get":{
            "operationId":"GenerateOpenAPI",
            "x-ISC_ServiceMethod":"GenerateOpenAPI",
            "responses":{
               "default":{
                  "description":"(Unexpected Error)"
               },
               "200":{
                  "description":"(Expected Result)"
               }
            }
         }
      }
   },
   "swagger":"2.0"
}