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

引入依赖

io.quarkus quarkus-smallrye-openapi

添加完以上依赖后，在开发和测试环境会自动激活组件，并注册/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规范注解详细的描述接口信息

应用基础信息定义

/** * @author kl : http://kailing.pub * @version 1.0 * @date 2020/7/14 11:29 */ @OpenAPIDefinition( info = @Info( title = "用户信息系统接口", version = "1.0.1", description = "这个信息是用来描述swagger ui接口的，你可以根据这个信息来了解这个系统的api情况", contact = @Contact( name = "kl博主", url = "http://kailing.pub", email = "632104866@qq.com") ) ) public class SwaggerConfig extends Application { }

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

效果如下：

接口信息定义

/** * @author kl : http://kailing.pub * @version 1.0 * @date 2020/7/14 11:05 */ @Path("/user") @Produces(MediaType.APPLICATION_JSON) @Consumes(MediaType.APPLICATION_JSON) @Tag(name = "UserResource",description = "用户接口列表") public class UserResource { @POST @Path("/add") @Operation(summary = "创建用户", description = "这是一个创建用户的接口") public String createUser(UserDto userDto) { return "hello"; } @POST @Path("/update") @Operation(summary = "更新用户", description = "这是更新用户的接口") public UserDto update(@RequestBody(description = "更新用户实体", required = true, content = @Content(schema = @Schema(implementation = UserDto.class))) UserDto userDto) { return userDto; } @GET @Path("/{userId}") @Operation(summary = "查找用户", description = "这是查找用户的接口") @APIResponse(responseCode = "400", description = "找不到这个用户") public UserDto findUser(@Parameter(description = "用户的ID", required = true) @PathParam("userId") Integer userId){ return new UserDto(); } /** * 使用 @Operation(hidden = true) 隐藏这个api，不在swagger ui中展示 */ @GET @Path("/hello") @Operation(hidden = true) public String hello(){ return "hello"; } }

效果如下：

传输实体定义

/** * @author kl : http://kailing.pub * @version 1.0 * @date 2020/7/14 11:12 */ @Schema( description = "这是一个用户的传输实体") public class UserDto { //隐藏内部使用的属性 @Schema(hidden = true) private Integer id; @Schema(title = "姓名", required = true, example = "kl") private String name; @Schema(title = "年龄", required = true, maximum = "120",minimum = "1",example = "19", type = SchemaType.INTEGER) private Integer age; }

效果如下：

结语

在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的资料请关注其它相关文章！

版权声明：本文内容由网络用户投稿，版权归原作者所有，本站不拥有其著作权，亦不承担相应法律责任。如果您发现本站中有涉嫌抄袭或描述失实的内容，请联系我们jiasou666@gmail.com 处理，核实后本网站将在24小时内删除侵权内容。