聚集 REST API 文档

您可以使用支持 MicroProfile OpenAPI 规范的 openapi-3.1 功能部件来聚集所生成的 REST API 文档。记录 REST API ，指定公共和专用 API ，并将 Web 应用程序部署到 Liberty 服务器。然后，您可以在使用人员友好用户界面的浏览器中查看 openapi-3.1 所生成的 API 文档。

已稳定的功能部件: openapi-3.1 功能部件已稳定。您可继续使用该功能部件。但是，策略替代方法是使用 MicroProfile OpenAPI 功能部件，例如 mpOpenAPI-3.0。

准备工作

openapi-3.1 功能部件是对 mpOpenAPI-1.0 功能部件的扩展，后者实现 MicroProfile OpenAPI 规范。有关 mpOpenAPI-1.0 功能部件的更多信息，请参阅使用 MicroProfile OpenAPI 1.0。

过程

构建 OpenAPI 文档。请查看使用 MicroProfile OpenAPI生成 REST API 文档以了解有关构建文档的过程。
在 Liberty 服务器配置中启用 openapi-3.1 功能部件。
1. 将 openapi-3.1 功能部件添加到功能部件管理器:
```
<server>
   <featureManager>
      <feature>openapi-3.1</feature>
   </featureManager>
</server>
```
2. 可选: 指定应用程序 OpenAPI 是专用的。缺省情况下，OpenAPI 文档为公用。所有用户都可以访问公用 API，且通常无需进行认证。公共 API 记录在 /api/docs resource中。您可以指定 API 保持专用。用于管理用途的 API 通常保持专用。使用密码进行保护的专用 API 记录在 /ibm/api/docs 资源中。此资源记录所有专用 API 和所有公用 API。通过在应用程序级别设置 MicroProfile 配置属性 mp.openapi.extensions.liberty.public=false，可以为 Web 应用程序指定专用 API。缺省情况下，此属性的值为 true。需要此配置仅仅是为了禁用您想要保持专用的应用程序。
3. 可选: 指定应用程序未显示在 OpenAPI 文档中。缺省情况下，包含 REST API 文档的 Web 模块会出现在 /api/docs 资源中提供的已合并 OpenAPI 文档中。要使 Web 模块不出现在该 OpenAPI 文档中，请设置以下 MicroProfile 配置属性的值：mp.openapi.extensions.liberty.exclude.context.roots。此属性的值是一列要隐藏的上下文根，以逗号分隔。请通过上下文根指示每个要隐藏的 Web 模块，并将这些上下文根添加到该属性的值。例如，要隐藏上下文根为 /airlinesAdmin 的 Web 模块，请设置 mp.openapi.extensions.liberty.exclude.context.roots=/airlinesAdmin。当启用 openapi-3.1 功能部件时，将读取此属性。
部署应用程序。
您可以使用下列其中一个 URL 在 /api/docs 端点上找到生成的 API 文档，具体取决于您的 API 是公用的还是专用的。
- - 对于非 SSL 公用 API，请在 http://Liberty_host:http_port/api/docs 处查看文档。
  - 对于 SSL 公用 API，请在 https://Liberty_host:https_port/api/docs 处查看文档。
  - 对于 SSL 专用 API，请在 https://Liberty_host:https_port/ibm/api/docs 处查看文档。
提示：
缺省情况下，服务器有两个可用的端点。
- GET http://Liberty_host:http_port/api/docs
  
  GET http://Liberty_host:http_port/api/explorer
您可使用 MicroProfile 配置属性 mp.openapi.extensions.liberty.public.url 来定制公用端点的 URL。启用 openapi-3.1 功能部件时，将会读取此属性。以下示例说明使公用 REST API 文档可通过 GET http://Liberty_host:http_port/myAPI/docs 和 http://Liberty_host:http_port/myAPI/explorer 获得的 MicroProfile 配置。
```
mp.openapi.extensions.liberty.public.url=myAPI
```
将生成 OpenAPI 文档，并在该 Liberty 服务器的应用程序之间进行聚集。缺省情况下，该文档采用 YAML 格式。如果 HTTP 请求包含值为 application/json 的 Accept 标头，那么表明该文档采用 JSON 格式。或者，可以使用 format 查询参数：http://Liberty_host:http_port/api/docs?format=json
提示：
可以按上下文根来过滤 OpenAPI 文档。公用端点 (api/docs) 和专用端点 (ibm/api/docs) 都支持查询参数 root，该参数可过滤所找到的上下文根。例如，以下调用：
GEThttp://Liberty_host:http_port/api/docs?root=/myApp 检索仅包含 myApp 上下文根文档的 OpenAPI V3 文档。

结果

OpenAPI 用户界面将呈现从 /api/docs 聚集的定义（位于 http://Liberty_host:http_port/api/explorer）。如果启用了 SSL，您可以通过 https://Liberty_host:https_port/api/explorer 访问受保护的 UI。

可以通过设置以下 MicroProfile 配置属性来浏览专用 Web 模块：mp.openapi.extensions.liberty.enable.private.url=true。启用 openapi-3.1 功能部件时，将会读取此属性。

启用专用 Web 模块浏览后，请使用 https://Liberty_host:https_port/ibm/api/explorer 针对公用和专用 Web 模块显示人员友好 UI。

在此用户界面中可以查看应用程序中的所有 RESTful 端点。另外，还可以过滤所显示的端点，将注意力集中在特定的应用程序。