使用 OpenAPI 生成 REST API 文档

您可以使用支持 OpenAPI 规范的 openapi-3.0 功能部件来生成 REST API 文档。为您的REST API编写文档，指定公共API和私有API，选择启用注解扫描功能，并将Web应用程序部署到 Liberty 服务器。然后，您可以在使用人员友好用户界面的浏览器中查看 openapi-3.0 所生成的 API 文档。

已稳定的功能：OpenAPI 的 V3 功能、 openapi-3.0 以及 openapi-3.1、均已稳定。您可继续使用这些功能部件。然而，另一种策略是使用 MicroProfile 的 OpenAPI 功能，例如 mpOpenAPI-3.0。

有关在Liberty系统中使用 MicroProfile （ OpenAPI ）的更多信息，请访问 Open Liberty 网站

准备工作

了解 OpenAPIV3 规范。可以使用 YAML 或 JSON 文件来记录您的应用程序中的 RESTful API。

您可以使用 MicroProfileOpenAPI 规范（版本 1.0 ）提供的Java接口和编程模型。 mpOpenAPI-1.0 功能部件实现 MicroProfile OpenAPI 规范。有关 mpOpenAPI-1.0 及后续功能的更多信息，请参阅《使用 MicroProfile 生成REST API文档》 OpenAPI。

有关此任务

可以使用以下样本应用程序来探查这些功能部件，例如，新的用户界面、注释和编程接口。

尝试使用Java™代码中的 OpenAPI 注解来为RESTful应用程序添加文档，具体可参考 OpenAPI 的 V3 注解示例应用程序。
查看使用文本编辑器创建的 OpenAPI V3 YAML格式文档示例，该文档采用 OpenAPI V3 示例文档格式。
通过使用 OpenAPIConfiguration 编程 io.swagger.oas.integration.OpenAPIConfigurationBuilder 接口示例，扩展该 openapi-3.0 功能。

过程

构建 OpenAPI 文档。
您可以通过多种方式来记录和构建 OpenAPI：
- 在Java代码中指定 OpenAPI 注解，以增强和记录应用程序。
- 在文本编辑器中使用 OpenAPI 标记来记录 API，然后将已完成的 openapi.yaml、openapi.yml 或 openapi.json 文件放置在应用程序的 META-INF 目录中。
- 使用 io.swagger.oas.integration.OpenAPIConfigurationBuilder 编程接口从应用程序内构建 OpenAPI 模型。您可以在 /wlp/dev/api/third-party 目录中的 JAR 文件内找到此接口以及 OpenAPI V3 的其他相关编程接口。要使 openapi-3.0 功能部件启动 OpenAPIConfigurationBuilder，应用程序归档必须具有 META-INF/services/io.swagger.oas.integration.OpenAPIConfigurationBuilder 文件。此文件的内容是 OpenAPIConfigurationBuilder 的标准名称。
  有关可用编程接口的更多信息、功能说明及其使用示例，请参阅 OpenAPI V3 programming interfaces。
在 Liberty 服务器配置中启用该 openapi-3.0 功能。
1. 将该 openapi-3.0 功能添加到功能管理器中。
```
<server>
   <featureManager>
      <feature>openapi-3.0</feature>
   </featureManager>
</server>
```
2. 可选：指定应用程序 OpenAPI 为私有。
  
  缺省情况下，OpenAPI 文档为公用。所有用户都可以访问公用 API，且通常无需进行认证。公用 API 记录在 /api/docs 资源中。
  您可以指定 API 保持专用。用于管理用途的 API 通常保持专用。使用密码进行保护的专用 API 记录在 /ibm/api/docs 资源中。此资源记录所有专用 API 和所有公用 API。
  
  可以通过两种方式指定用于 Web 应用程序的专用 API：
  - 在服务器配置中使用 webModuleDoc，并将 public 属性设置为 false。
    1. 添加 openapi 元素并将其布尔属性 enablePrivateURL 设置为 true。
    2. 为每个 Web 应用程序添加一个 webModuleDoc 子元素，并将其布尔属性 public 设置为 true（对于公用 API）和 false（对于专用 API）。
    以下示例使 airlines 应用程序 OpenAPI 可见，并禁止公开 airlinesAdmin 应用程序 OpenAPI。
```
<openapi enablePrivateURL="true">
  <webModuleDoc contextRoot="/airlines" public="true" />
  <webModuleDoc contextRoot="/airlinesAdmin" public="false" />
</openapi>
```
    缺省情况下，webModuleDoc 的 public 属性设置为 true。需要此配置仅仅是为了禁用您想要保持专用的应用程序。
  - 在 API 描述中使用供应商扩展关键字指定 API 是专用 API。
    1. 向服务器配置中添加 openapi 元素，并将其布尔属性 enablePrivateURL 设置为 true。
    2. 将 x-ibm-private: true 关键字和值放置在 API 描述文档 META-INF/openapi.yaml 文件中或另一种受支持格式的文件中。此值会覆盖 API 的缺省可见性，并且此值可被 webModuleDoc 条目覆盖。
3. 可选：指定应用程序不显示在 OpenAPI 文档中。
  
  缺省情况下，包含 REST API 文档的 Web 模块会出现在 /api/docs 资源中提供的已合并 OpenAPI 文档中。要使 Web 模块不出现在该 OpenAPI 文档中，请更改服务器配置中的 webModuleDoc 元素的属性。
  使用 contextRoot 属性标识您想要隐藏或显示的 Web 模块。然后，将 enabled 属性更改为 false 以便在 OpenAPI 文档中隐藏该 Web 模块。 enabled 属性的缺省值是 true。在以下示例中，对 airlines 模块进行了配置，以使其出现在 OpenAPI 文档中，而 airlinesAdmin 模块将隐藏。
```
<openapi>
  <webModuleDoc contextRoot="/airlines" enabled="true" />
  <webModuleDoc contextRoot="/airlinesAdmin" enabled="false" />
</openapi>
```
  注意：对于由其他Liberty 功能提供的REST API文档，不支持该 enabled 属性。
可选：启用 JAX-RS 注解扫描。

将 jaxrs-2.0 功能部件添加至功能部件管理器。如果服务器中同时启用了 jaxrs-2.0 和 openapi-3.0 功能部件，那么除非服务器配置禁用扫描，否则注释扫描程序会扫描服务器上部署的所有 Web 应用程序。扫描程序会仔细检查类定义中使用 OpenAPI 3.0 注释进行注释的类以及使用 @Path JAX-RS 注释进行注释的类。您可以使用 OpenAPI 公用端点 (api/docs) 和专用端点 (ibm/api/docs) 来访问所生成的 OpenAPI 文档。
允许第三方 API 对特定应用程序可见。
要启用 OpenAPI 注释、模型和编程模型的运行时装入，您必须对特定应用程序启用第三方 API 可见性。
1. 将 classloader 元素的属性 apiTypeVisibility 定义为第三方API可见性。在您的 server.xml 文件中向 third-party 元素 classloader 添加。
  
  如果您未指定 classloader 来将 third-party 包括在 apiTypeVisibility 中，那么它使用 spec、stable 和 ibm-api 的缺省定义。
```
<application id="scholar" name="Scholar" type="ear" location="scholar.ear">
  <classloader apiTypeVisibility="spec, ibm-api, stable, third-party" commonLibraryRef="Alexandria" />
</application>
```
可选：启用对 OpenAPI 文档的验证。

缺省情况下，验证功能处于禁用状态。启用验证后，openapi-3.0 功能部件将根据 OpenAPI V3 规范中声明的约束来验证应用程序提供的每个 OpenAPI 文档。如果 openapi-3.0 找到无效的 OpenAPI 文档，那么此功能部件会针对每个违例约束在日志中报告错误。无效文档将从 api/docs 端点所返回的聚集 OpenAPI 文档中排除。要启用验证，请在 server.xml 文件中将 validationtrue 属性设置为。
```
<openapi validation="true"/>
```
部署应用程序。
在浏览器中查看所生成的 API 文档。
您可根据 API 是公用 API 还是专用 API，使用下列其中一个 URL 在 /api/docs 端点处找到所生成的 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
您可以在文件 server.xml 中使用属性 publicURL 为公共端点自定义 URL。以下示例说明了在文件 server.xml 中进行的配置，以使公共 REST API 文档可通过访问 GET http://Liberty_host:http_port/myAPI/docs and http://Liberty_host:http_port/myAPI/explorer。
```
<openapi publicURL="myAPI" />
```
OpenAPI 文档在该Liberty 服务器上跨应用程序生成并聚合。缺省情况下，该文档采用 YAML 格式。当您使用 Microsoft Internet Explorer 11查看文档时，它返回的YAML文档格式不正确。作为临时解决方案，请使用浏览器如 Mozilla、 Firefox 或 Google Chrome 浏览器。如果 http 请求包含值为 application/json 的 Accept 标头，那么表明该文档采用 JSON 格式。

提示：您可以通过上下文根过滤 OpenAPI 文档。公用端点 (api/docs) 和专用端点 (ibm/api/docs) 都支持查询参数 root，该参数可过滤所找到的上下文根。例如，调用 GET http://Liberty_host:http_port/api/docs?root=/myApp 可检索一个仅包含上下文 myApp 根文档的 OpenAPI V3 文档。

结果

OpenAPI 用户界面将呈现来自 /api/docs 的已聚集定义，以便在 http://Liberty_host:http_port/api/explorer 处显示人员友好 UI。如果启用了 SSL，您可以访问 https://Liberty_host:https_port/api/explorer 处的受保护 UI。

您可通过在文件的元素 openAPI 中启用属性 enablePrivateURLserver.xml 来浏览私有网页模块。

<openapi enablePrivateURL="true"/>

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

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