3.2 增加OpenAPI和SwaggerUI功能
Quarkus 框架的另一个与 REST服务相关的功能是对 OpenAPI的支持。通过 Quarkus 框架的OpenAPI扩展，可以生成OpenAPI的规范文档。
3.2.1 案例简介
本案例介绍基于 Quarkus 框架实现 REST的 OpenAPI功能。在应用程序添加了 OpenAPI扩展之后，在访问路径/openapi下可以得到基于OpenAPI v3规范的REST服务文档。OpenAPI扩展也自带了 Swagger界面，可以通过路径/swagger-ui来访问，可以同时了解一下 Quarkus 框架的 OpenAPI功能和集成 Swagger的使用方法。本案例的 OpenAPI遵循 Eclipse MicroProfile OpenAPI规范。
基础知识：OpenAPI规范、Eclipse MicroProfile OpenAPI规范和Swagger框架。
OpenAPI规范（OAS）为HTTP API定义了一个标准的、与语言无关的RESTful API规范描述，OpenAPI允许开发者和操作系统查看并理解服务的功能，而不需要访问源码、附加文档或检查网络流量。外部可读API定义文档的用例包括但不限于：交互式文档；文档、客户端和服务器的代码生成；以及测试用例的自动化。OpenAPI文档描述可以用YAML或JSON格式表示。这些文档可以静态地生成和提供，也可以从应用程序中动态生成。OpenAPI规范的结构如图3-7所示。
图3-7 OpenAPI规范的结构
Eclipse MicroProfile OpenAPI规范旨在为OpenAPI v3规范提供统一的Java API，所有应用程序开发者都可以使用它来公开 API文档。SpecAPI由注解、模型和编程接口组成。规范文档简要介绍了规范的规则。Swagger 框架实际上就是一个基于 OpenAPI 规范生成 API 文档的工具。该工具是一个规范和完整的框架，用于生成、描述、调用和可视化 RESTful 风格的 Web服务。Swagger 的总体目标是使客户端和文件系统作为服务器，以同样的速度进行更新。其API 文件的方法、参数和模型紧密集成到服务端的代码中，允许 API 始终保持同步。Swagger UI 提供了一个可视化的页面，用于展示描述文件。该工具支持在线导入描述文件和本地部署UI项目。
3.2.2 编写程序代码
编写程序代码有 3种方式。第 1种方式是通过代码 UI来实现的，在 Quarkus 官网的生成代码页面中按照指定步骤生成脚手架代码，然后下载文件，将项目引入 IDE 工具中，最后修改程序源码。
第2种方式是通过mvn来构建程序，通过下面的命令创建Maven项目来实现：
第3种方式是直接从GitHub上获取代码，可以从GitHub上克隆预先准备好的示例代码：
该程序位于“021-quarkus-sample-openapi-swaggerui”目录中，是一个 Maven 工程项目程序。
在IDE工具中导入Maven工程项目程序，在pom.xml的<dependencies>下有如下内容：
quarkus-smallrye-openapi是Quarkus 整合了OpenAPI和SwaggerUI服务的实现。
quarkus-sample-openapi-swaggerui 程序的应用架构（见图 3-8）表明，外部访问ProjectResource 资源接口，ProjectResource 资源依赖于 SmallRye OpenAPI 扩展（遵循MicroProfile OpenAPI规范）和Swagger框架，因此能提供OpenAPI的信息展现。
图3-8 quarkus-sample-openapi-swaggerui程序应用架构图
该案例的程序代码与quarkus-sample-rest-json案例的程序代码相似，就不再重复列出了。
3.2.3 验证程序
通过下列几个步骤（如图3-9所示）来验证案例程序。
图3-9 quarkus-sample-openapi-swaggerui程序验证流程图
下面对其中涉及的关键点进行说明。
1.启动quarkus-sample-openapi-swaggerui程序服务
启动程序有两种方式，第 1种是在开发工具（如 Eclipse）中调用 ProjectMain类的 run方法，第2种是在程序目录下直接运行命令mvnw compile quarkus：dev。
2.通过API显示项目OpenAPI的JSON列表内容
在命令行窗口中键入命令curl http：//localhost：8080/openapi。其返回所有项目所有OpenAPI的 JSON 列表。也可以通过浏览器 URL（http：//localhost：8080/openapi）获取一个 OpenAPI 文档，其内容如下：
该 OpenAPI 文档是按照 info、path、components 等层级的 JSON 列出的，遵循 OpenAPI 3.0规范。
3.显示UI界面
在浏览器中显示 UI 界面，输入 URL（http：//localhost：8080/swagger-ui）。从其返回界面（如图3-10所示）可以获得所有的API方法及其内容。
图3-10 OpenAPI和SwaggerUI界面
通过图 3-10，可以了解微服务的 GET、PUT、POST、DELETE 等方法的参数和输出内容。单击方法GET，方法详细描述如图3-11所示。
图3-11 GET方法的详细描述
可以查看方法的Request body和Responses等具体内容，也可以阅读Schemas的内容，如图3-12所示。
图3-12 OpenAPI的Schemas内容
通过Schemas的内容，我们可以知道Project的结构，以及传入参数Project的结构。