Quarkus集成open api接口使用swagger ui展示

前言

quarkus中对swagger ui也有支持，但是和spring 中直接集成swagger ui功能不同，quarkus中使用open api规范得到接口的json数据，然后使用swagger ui展示。所以在quarkus中集成swagger ui时，会发现没有swagger ui那些接口标记注解了，取而代之的是open api规范中的注解。下面来捋一捋他们的关系，看看怎么在quarkus中使用。

microprofile-open-api-doc:https://eclipse.org/microprofile-open-api-1.0

组件关系

 openapi v3规范：

openapi规范（oas）定义了与restful api的语言无关的标准接口，使人类和计算机都可以发现和理解服务的功能，而无需访问源代码，文档或通过网络流量检查。正确定义后，使用者可以使用最少的实现逻辑来理解远程服务并与之交互。然后，文档生成工具可以使用openapi定义来显示api，代码生成工具可以使用各种编程语言来生成服务器和客户端，测试工具以及许多其他用例也可以使用openapi定义。

microprofile-open-api

此microprofile规范称为openapi 1.0，旨在提供一组java接口和编程模型，使java开发人员可以从其jax-rs应用程序本地生成openapi v3文档。

smallrye-open-api

smallrye openapi是eclipse microprofile openapi的具体实现。

综上可知，在quarkus中，最终使用的是smallrye-open-api。它是openapi v3协议java版本的具体实现

集成open api

引入依赖

添加完以上依赖后，在开发和测试环境会自动激活组件，并注册/openapi接口，通过这个接口可以获取openapiv3文档，请求http://localhost:8080/openapi即可。同时也会注册/swagger-ui接口，访问http://localhost:8080/swagger-ui就可以看到如下的界面：

默认情况下，swagger ui只会在开发测试环境激活，如果你想在生产环境也使用swagger-ui，需要在application.properties中添加quarkus.swagger-ui.always-include=true来激活，这个配置是编译时生效的，编译完成后无法更改。前面已经说过，quarkus集成了open api导出接口数据使用swagger ui展示的，所有集成起来非常简单，下面看下如何使用open api的java规范注解详细的描述接口信息

应用基础信息定义

openapi中使用@openapidefinition描述应用基础信息，可以类比swagger中的@swaggerdefinition注解

效果如下：

接口信息定义

效果如下：

传输实体定义

效果如下：

结语

在quarkus中使用swagger ui，openapi v3变成了主角。swagger ui单纯的变成了展示openapi v3数据的ui。所以使用方式上也区别了在spring环境中使用的方式，那些熟悉的swagger ui本身定义的注解都没有了，需要重新学习microprofile-open-api中定义的注解了，好在注解变化不大，学习起来没啥难度

以上就是quarkus集成open api接口使用swagger ui展示的详细内容，更多关于quarkus集成open api展示swagger ui的资料请关注其它相关文章！