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

 更新时间:2022年02月23日 16:21:11   作者:kl  
这篇文章主要为大家介绍了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

引入依赖

<dependency>
            <groupId>io.quarkus</groupId>
            <artifactId>quarkus-smallrye-openapi</artifactId>
</dependency>

添加完以上依赖后,在开发和测试环境会自动激活组件,并注册/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://www.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的资料请关注脚本之家其它相关文章!

相关文章

  • C++排序算法之桶排序原理及实现详解

    C++排序算法之桶排序原理及实现详解

    这篇文章主要介绍了C++排序算法之桶排序原理及实现详解, C++ 桶排序是一种线性时间复杂度的排序算法,它通过将待排序元素分配到不同的桶中,然后对每个桶中的元素进行排序,最后将所有桶中的元素按顺序合并得到有序序列,需要的朋友可以参考下
    2023-10-10
  • SpringBoot中注解@ConfigurationProperties与@Value的区别与使用详解

    SpringBoot中注解@ConfigurationProperties与@Value的区别与使用详解

    本文主要介绍了SpringBoot中注解@ConfigurationProperties与@Value的区别与使用,具有一定的参考价值,感兴趣的小伙伴们可以参考一下
    2021-09-09
  • XML Web 服务 Eclipse实现sun-jaxws.xml文件的方法

    XML Web 服务 Eclipse实现sun-jaxws.xml文件的方法

    在sun-jaxws.xml文件,可以配置endpoint、handler-chain等内容,在这个文件中配置的内容会覆盖在Java代码中使用注解属性配置的的内容,本文给大家介绍的非常详细,感兴趣的朋友一起看看吧
    2023-11-11
  • 关于mybatis-plus插件使用时的一些问题小结

    关于mybatis-plus插件使用时的一些问题小结

    这篇文章主要给大家介绍了关于mybatis-plus插件使用时的一些问题的相关资料,文中通过实例代码介绍的非常详细,对大家的学习或者工作具有一定的参考学习价值,需要的朋友可以参考下
    2022-03-03
  • java通过方向键控制小球移动的小游戏

    java通过方向键控制小球移动的小游戏

    这篇文章主要为大家详细介绍了java通过方向键控制小球移动的小游戏,文中示例代码介绍的非常详细,具有一定的参考价值,感兴趣的小伙伴们可以参考一下
    2021-10-10
  • Java使用Hutool+自定义注解实现数据脱敏

    Java使用Hutool+自定义注解实现数据脱敏

    我们在使用手机银行的时候经常能看到APP上会将银行卡的卡号中间部分给隐藏掉使用 ***** 来代替,在某些网站上查看一些业务密码时(例如签到密码等)也会使用 ***** 来隐藏掉真正的密码,那么这种方式是如何实现的呢,本文将给大家介绍使用Hutool+自定义注解实现数据脱敏
    2023-09-09
  • Java 分析并解决内存泄漏的实例

    Java 分析并解决内存泄漏的实例

    这篇文章主要介绍了Java 分析并解决内存泄漏的实例,帮助大家更好的理解和学习Java,感兴趣的朋友可以了解下
    2020-08-08
  • Java中实现简单的Excel导出

    Java中实现简单的Excel导出

    今天小编就为大家分享一篇关于Java中实现简单的Excel导出,小编觉得内容挺不错的,现在分享给大家,具有很好的参考价值,需要的朋友一起跟随小编来看看吧
    2019-01-01
  • Java中 URL实现断点下载

    Java中 URL实现断点下载

    Java中 URL实现断点下载,需要的朋友可以参考一下
    2013-03-03
  • Java如何使用HTTPclient访问url获得数据

    Java如何使用HTTPclient访问url获得数据

    这篇文章主要介绍了Java使用HTTPclient访问url获得数据的操作,具有很好的参考价值,希望对大家有所帮助。如有错误或未考虑完全的地方,望不吝赐教
    2021-09-09

最新评论