文章
姚 鑫 · 七月 28 阅读大约需 4 分钟

第十章 发现和记录 REST API

第十章 发现和记录 REST API

本章讨论如何发现实例上可用的 REST 服务以及如何为 REST 服务生成文档。

使用 /api/mgmnt 服务发现 REST 服务

/api/mgmnt 服务包括可用于发现 REST 服务类和启用 RESTWeb 应用程序的调用。

发现 REST 服务

要使用 /api/mgmnt 服务来发现实例上可用的 REST 服务,请使用以下 REST 调用:

  • 对于 HTTP 操作,选择或指定 GET
  • 对于 URL,请指定以下形式的 URL
http://localhost:52773/api/mgmnt/v2/

或者,如果只想检查一个命名空间:

http://localhost:52773/api/mgmnt/v2/:namespace

其中 localhost 是服务器的名称,52773 是运行 IRISWeb 服务器端口,命名空间是要检查的命名空间。

(请注意,这些调用会忽略手动编码的 REST 服务。要发现手动编码的 REST 应用程序,请使用调用 GET /api/mgmnt/GET /api/mgmnt/:v1/:namespace/restapps。)

如果调用成功,IRISJSON 格式返回一个列出 REST 服务的数组。例如:

[
  {
    "name": "%Api.Mgmnt.v2",
    "webApplications": "/api/mgmnt",
    "dispatchClass": "%Api.Mgmnt.v2.disp",
    "namespace": "%SYS",
    "swaggerSpec": "/api/mgmnt/v2/%25SYS/%Api.Mgmnt.v2"
  },
  {
    "name": "myapp",
    "webApplications": "/api/myapp",
    "dispatchClass": "myapp.disp",
    "namespace": "USER",
    "swaggerSpec": "/api/mgmnt/v2/USER/myapp"
  }
]

发现支持 RESTWeb 应用程序

要使用 /api/mgmnt 服务来发现实例上可用的支持 RESTWeb 应用程序,请使用以下 REST 调用:
- 对于 HTTP 操作,选择或指定 GET
- 对于 URL,请指定以下形式的 URL

http://localhost:52773/api/mgmnt

或者,如果只想检查一个命名空间:

http://localhost:52773/api/mgmnt/v1/:namespace/restapps

其中 localhost 是服务器的名称,52773 是运行 IRISWeb 服务器端口,命名空间是要检查的命名空间。

使用 %REST.API 类发现 REST 服务

%REST.API 类提供可用于发现 REST 服务类和启用 RESTWeb 应用程序的方法。

发现 REST 服务类

要使用 %REST.API 类来发现实例上可用的 REST 服务,请使用该类的以下方法:

  • GetAllRESTApps()
GetAllRESTApps(Output appList As %ListOfObjects) as %Status

返回此服务器上的 REST 服务列表作为输出。输出参数 applist%ListOfObjects 的实例,列表中的每一项都是 %REST.Application 的实例,其中包含有关 REST 服务的信息。这包括没有关联 Web 应用程序的任何 REST 服务。此方法忽略任何手动编码的 REST 服务。

  • GetRESTApps()
GetRESTApps(namespace as %String,
            Output appList As %ListOfObjects) as %Status

以输出形式返回由命名空间指示的命名空间中的 REST 服务列表。

发现支持 RESTWeb 应用程序

要使用 %REST.API 类来发现实例上可用的支持 RESTWeb 应用程序,请使用该类的以下方法:

  • GetAllWebRESTApps()
GetAllWebRESTApps(Output appList As %ListOfObjects) as %Status

返回此服务器上启用 RESTWeb 应用程序的列表作为输出。输出参数 applist%ListOfObjects 的实例,列表中的每个项目都是 %REST.Application 的实例,其中包含有关 Web 应用程序的信息。

  • GetWebRESTApps()
GetWebRESTApps(namespace as %String,
               Output appList As %ListOfObjects) as %Status

作为输出,返回由命名空间指示的命名空间中支持 RESTWeb 应用程序的列表。请参阅 GetAllWebRESTApps()

REST 服务提供文档

记录任何 API 很有用,以便开发人员可以轻松使用 API。对于遵循 OpenAPI 2.0 规范的 REST API,可以使用 Swagger 开源框架根据规范的内容为您的 API 提供交互式文档。

一种选择是使用 Swagger UI 并提供文档的托管副本。对于演示:
1. 转到 https://swagger.io/tools/swagger-ui/
2. 单击 Live Demo
3. 在页面顶部的框中,以 JSON 格式输入 REST 服务的 OpenAPI 2.0 规范的 URL

例如,在 IRIS 服务器上使用 GET /api/mgmnt/v2/:namespace/:application 调用。

  1. 然后页面的下部显示文档,如以下示例所示:

在这里,可以查看有关每个呼叫的详细信息、测试呼叫并查看响应。

其他第三方工具使能够生成静态 HTML。 对此没有具体建议。

0
0 12
讨论 (0)1
登录或注册以继续