# 第十章 发现和记录 REST API 本章讨论如何发现实例上可用的 `REST` 服务以及如何为 `REST` 服务生成文档。 # 使用 `/api/mgmnt` 服务发现 `REST` 服务 `/api/mgmnt` 服务包括可用于发现 `REST` 服务类和启用 `REST` 的 `Web` 应用程序的调用。 ## 发现 `REST` 服务 要使用 `/api/mgmnt` 服务来发现实例上可用的 `REST` 服务,请使用以下 `REST` 调用: - 对于 `HTTP` 操作,选择或指定 `GET`。 - 对于 `URL`,请指定以下形式的 `URL`: ```java http://localhost:52773/api/mgmnt/v2/ ``` 或者,如果只想检查一个命名空间: ```java http://localhost:52773/api/mgmnt/v2/:namespace ``` 其中 `localhost` 是服务器的名称,`52773` 是运行 `IRIS` 的 `Web` 服务器端口,命名空间是要检查的命名空间。 (请注意,这些调用会忽略手动编码的 `REST` 服务。要发现手动编码的 `REST` 应用程序,请使用调用 `GET /api/mgmnt/` 和 `GET /api/mgmnt/:v1/:namespace/restapps`。) 如果调用成功,`IRIS` 以 `JSON` 格式返回一个列出 `REST` 服务的数组。例如: ```java [ { "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" } ] ``` ## 发现支持 `REST` 的 `Web` 应用程序 要使用 `/api/mgmnt` 服务来发现实例上可用的支持 `REST` 的 `Web` 应用程序,请使用以下 `REST` 调用: - 对于 `HTTP` 操作,选择或指定 `GET`。 - 对于 `URL`,请指定以下形式的 `URL`: ```java http://localhost:52773/api/mgmnt ``` 或者,如果只想检查一个命名空间: ```java http://localhost:52773/api/mgmnt/v1/:namespace/restapps ``` 其中 `localhost` 是服务器的名称,`52773` 是运行 `IRIS` 的 `Web` 服务器端口,命名空间是要检查的命名空间。 # 使用 `%REST.API` 类发现 `REST` 服务 `%REST.API` 类提供可用于发现 `REST` 服务类和启用 `REST` 的 `Web` 应用程序的方法。 ## 发现 `REST` 服务类 要使用 `%REST.API` 类来发现实例上可用的 `REST` 服务,请使用该类的以下方法: - `GetAllRESTApps()` ```java GetAllRESTApps(Output appList As %ListOfObjects) as %Status ``` 返回此服务器上的 `REST` 服务列表作为输出。输出参数 `applist` 是 `%ListOfObjects` 的实例,列表中的每一项都是 `%REST.Application` 的实例,其中包含有关 `REST` 服务的信息。这包括没有关联 `Web` 应用程序的任何 `REST` 服务。此方法忽略任何手动编码的 `REST` 服务。 - `GetRESTApps()` ```java GetRESTApps(namespace as %String, Output appList As %ListOfObjects) as %Status ``` 以输出形式返回由命名空间指示的命名空间中的 `REST` 服务列表。 ## 发现支持 `REST` 的 `Web` 应用程序 要使用 `%REST.API` 类来发现实例上可用的支持 `REST` 的 `Web` 应用程序,请使用该类的以下方法: - `GetAllWebRESTApps()` ```java GetAllWebRESTApps(Output appList As %ListOfObjects) as %Status ``` 返回此服务器上启用 `REST` 的 `Web` 应用程序的列表作为输出。输出参数 `applist` 是 `%ListOfObjects` 的实例,列表中的每个项目都是 `%REST.Application` 的实例,其中包含有关 `Web` 应用程序的信息。 - `GetWebRESTApps()` ```java GetWebRESTApps(namespace as %String, Output appList As %ListOfObjects) as %Status ``` 作为输出,返回由命名空间指示的命名空间中支持 `REST` 的 `Web` 应用程序的列表。请参阅 `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` 调用。 4. 然后页面的下部显示文档,如以下示例所示: 在这里,可以查看有关每个呼叫的详细信息、测试呼叫并查看响应。 其他第三方工具使能够生成静态 `HTML`。 对此没有具体建议。