前言
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
引入依赖
1
2
3
4
|
< 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规范注解详细的描述接口信息
应用基础信息定义
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
|
/** * @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注解
效果如下:
接口信息定义
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
|
/** * @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" ; } } |
效果如下:
传输实体定义
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
|
/** * @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的资料请关注服务器之家其它相关文章!
原文链接:http://www.kailing.pub/article/index/arcid/291.html