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 功能部件,那么在您访问
/openapi 或 openapi/ui 端点时,可能会出现异常。要避免此问题,请同时启用这两个功能部件。要在发生此问题后加以解决,请禁用
mpOpenAPI-1.0 功能部件,然后将其启用。
如果部署了多个应用程序,将会选择一个应用程序来生成 OpenAPI 文档。系统会输出一条参考消息,以指出所选择的应用程序。如果所选应用程序正在运行,那么所有其他应用程序将被应用程序处理器忽略。在所选应用程序停止后,将处理下一个应用程序。
过程
- 可选: 根据您的应用程序的需要,通过 MicroProfile Config 机制配置 MicroProfile OpenAPI 规范的各个部分。 mpOpenAPI-1.0 功能部件将在应用程序启动时读取所配置的值。
- 针对您的应用程序,配置 MicroProfile OpenAPI 规范中提供的一项或多项核心配置。
- 要添加值,mpOpenAPI-1.0 功能部件将针对 OpenAPI V3.0
规范中声明的约束,验证为应用程序生成的最终 OpenAPI 文档。验证结果(即,错误和警告的组合)将输出到控制台日志。
缺省情况下,将对应用程序启用验证功能。您可以通过设置下列配置来禁用验证。
mp.openapi.extensions.liberty.validation=false
- 选择下列其中一种方法或下列方法的组合,为结果 OpenAPI 文档的生成提供输入,如文档机制所述。
- 使用编程模型提供引导程序或完整的 OpenAPI 模型树。
- 使用文本编辑器编写 YAML 或 JSON 格式的静态 OpenAPI 文档,然后将
openapi.yaml、openapi.yml 或 openapi.json
文件放置在应用程序的 META-INF 目录中。
- 在 Java 代码中指定 MicroProfile OpenAPI 注释,以扩充和记录应用程序。
- 在使用文档机制构建 OpenAPI 模型之后,使用过滤器更新该模型。
- 在 Liberty 服务器配置中启用 mpOpenAPI-1.0 功能部件。
<server>
<featureManager>
<feature>mpOpenAPI-1.0</feature>
</featureManager></server>
- 部署应用程序。
- 可选: 检查验证结果,并确保应用程序符合 OpenAPI V3.0 规范。
- 检查控制台日志中是否存在验证错误。
- 事件分组为错误和警告。消息还包含所生成文档中的相应位置,以帮助您确定相关元素。
样本消息:
CWWKO1650E: 验证 OpenAPI 文档生成下列错误:
- 消息:必填字段“scopes”缺失或设置为无效的值,位置:#/components/securitySchemes/reviewoauth/flows/authorizationCode
- 在浏览器中查看所生成的 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。