使用 OpenAPI 生成 REST API 文档

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

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

有关将 MicroProfile OpenAPI 与 Liberty配合使用的更多信息，请参阅 Open Liberty Web 站点

准备工作

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

您可以使用 MicroProfile OpenAPI Specification V 1.0中提供的 Java 接口和编程模型。 mpOpenAPI-1.0 功能部件实现 MicroProfile OpenAPI 规范。有关 mpOpenAPI-1.0 和更高版本的功能部件的更多信息，请参阅使用 MicroProfile OpenAPI。

有关此任务

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

尝试使用 OpenAPI V3 注释样本应用程序在 Java™ 代码中使用 OpenAPI 注释来记录 RESTful 应用程序。
请参阅使用 OpenAPI V3 示例文档通过文本编辑器创建的 YAML 格式的 OpenAPI V3 文档的示例。
通过将 io.swagger.oas.integration.OpenAPIConfigurationBuilder 编程接口与 OpenAPIConfiguration 编程接口示例配合使用，扩展 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 编程接口。
在 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 可视性。将 third-party 添加到 server.xml 文件中的 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 文件中将 validation 属性设置为 true 。
```
<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。

您可以通过在 server.xml 文件的 openAPI 元素中启用 enablePrivateURL 属性来浏览专用 Web 模块。

<openapi enablePrivateURL="true"/>

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

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