[18.0.0.1 and later]

使用 MicroProfile OpenAPI 1.0 生成 REST API 文档

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

开始之前

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

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

过程

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

用于指示主题类型的图标 任务主题

文件名:twlp_mpopenapi.html