使用 MicroProfile OpenAPI 生成 REST API 文档

mpOpenAPI-1.1 功能部件提供 MicroProfile OpenAPI 规范的实现，并提供一组 Java 接口和编程模型，供 Java 开发者用于从其 JAX-RS 应用程序在本地生成 OpenAPI V3 文档。 然后，您可以在使用人员友好用户界面的浏览器中查看使用 mpOpenAPI-1.1 功能部件所生成的 API 文档。

Open Liberty 有关使用 Liberty MicroProfile OpenAPI 功能部件 V 1.0 和更高版本的信息，请参阅 Open Liberty Web 站点

准备工作

了解 OpenAPI V3 规范 和 MicroProfile OpenAPI 1.1 规范 或 MicroProfile OpenAPI 1.0 规范。 您可以使用 YAML 格式或 JSON 格式的静态 OpenAPI 文件、MicroProfile OpenAPI 注释或 OpenAPI 编程模型来记录您的应用程序中的 RESTful API。
避免麻烦:
  • 扩展和扩展注释仅在操作级别和类级别受支持。 请使用其他文档机制为其他元素指定扩展。
  • 如果您第一次输入不正确的授权凭证，OpenAPI UI 会出现意外行为。 即使随后输入正确的凭证，该问题也仍然存在，并且可能会重复提示您输入凭证。 请刷新页面并输入正确的凭证。
  • 如果在启用 mpOpenAPI-1.1 之后启用 transportSecurity-1.0 功能部件，那么在您访问 /openapi 或 openapi/ui 端点时，可能会出现异常。 要避免此问题，请同时启用这两个功能部件。 要在发生此问题后加以解决，请禁用 mpOpenAPI 功能部件，然后将其启用。

如果部署了多个应用程序，将会选择一个应用程序来生成 OpenAPI 文档。 系统会输出一条参考消息，以指出所选择的应用程序。 如果所选应用程序正在运行，那么所有其他应用程序将被应用程序处理器忽略。 在所选应用程序停止后，将处理下一个应用程序。

过程

  1. 可选: 根据应用程序需要，通过 MicroProfile config 机制配置 MicroProfile OpenAPI 规范的各个部分。
    mpOpenAPI-1.1 功能部件将在应用程序启动时读取所配置的值。
    • 配置应用程序的 MicroProfile OpenAPI 规范中提供的一个或多个 核心配置 。
    • 要添加值，mpOpenAPI-1.1 功能部件将针对 OpenAPI V3.0 规范中声明的约束，验证为应用程序生成的最终 OpenAPI 文档。 验证结果（即，错误和警告的组合）将输出到控制台日志。
      缺省情况下，将对应用程序启用验证功能。 您可以通过设置下列配置来禁用验证。
      mp.openapi.extensions.liberty.validation=false
  2. 按照 文档机制中的描述，选择以下一种或多种方法来为生成生成的 OpenAPI 文档提供输入。
    • 使用 编程模型 来提供引导程序或完整的 OpenAPI 模型树。
    • 使用文本编辑器以 YAML 或 JSON 格式编写 静态 OpenAPI 文档 ，然后将 openapi.yaml， openapi.yml或 openapi.json 文件放在应用程序的 META-INF 目录中。
    • 在 Java 代码中指定 MicroProfile OpenAPI 注释 以扩充和记录应用程序。
    • 使用 过滤器 在使用文档机制构建 OpenAPI 模型后对其进行更新。
  3. 在 Liberty 服务器配置中启用 mpOpenAPI-1.1 功能部件。
    <server>
   <featureManager>
      <feature>mpOpenAPI-1.1</feature>
   </featureManager>
</server>
  4. 部署应用程序。
  5. 可选: 检查验证结果，并确保应用程序符合 OpenAPI 规范版本 3.0。
    • 检查控制台日志中是否存在验证错误。
    • 事件分组为错误和警告。 消息还包含所生成文档中的相应位置，以帮助您确定相关元素。
      样本消息：
      CWWKO1650E: Validation of the OpenAPI document produced the following error(s):

 - Message: Required "scopes" field is missing or is set to an invalid value, Location: #/components/securitySchemes/reviewoauth/flows/authorizationCode
  6. 在浏览器中查看所生成的 API 文档。
    您可以使用下列其中一个 URL，在 /openapi 端点处查找所生成的 API 文档。
    • 对于非 SSL 公用 API，请在 http://Liberty_host:http_port/openapi 处查看您的文档。
    • 对于 SSL 公用 API，请在 https://Liberty_host:https_port/openapi 处查看您的文档。

结果

OpenAPI 用户界面将呈现 /openapi 中的定义，以便在 http://Liberty_host:http_port/openapi/ui 处显示 UI。 如果启用了 SSL，您可以在 https://Liberty_host:https_port/openapi/ui 处访问受保护的 UI。