快捷導(dǎo)航

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

更新時(shí)間：2022年02月23日 16:21:11 作者：kl

這篇文章主要為大家介紹了Quarkus集成open?api接口使用swagger?ui的展示示例，有需要的朋友可以借鑒參考下，希望能夠有所幫助，祝大家多多進(jìn)步

前言

Quarkus中對(duì)swagger ui也有支持，但是和spring 中直接集成swagger ui功能不同，Quarkus中使用open api規(guī)范得到接口的json數(shù)據(jù)，然后使用swagger ui展示。所以在Quarkus中集成swagger ui時(shí)，會(huì)發(fā)現(xiàn)沒(méi)有swagger ui那些接口標(biāo)記注解了，取而代之的是open api規(guī)范中的注解。下面來(lái)捋一捋他們的關(guān)系，看看怎么在Quarkus中使用。

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

組件關(guān)系

OpenAPI V3規(guī)范：

OpenAPI規(guī)范（OAS）定義了與RESTful API的語(yǔ)言無(wú)關(guān)的標(biāo)準(zhǔn)接口，使人類(lèi)和計(jì)算機(jī)都可以發(fā)現(xiàn)和理解服務(wù)的功能，而無(wú)需訪問(wèn)源代碼，文檔或通過(guò)網(wǎng)絡(luò)流量檢查。正確定義后，使用者可以使用最少的實(shí)現(xiàn)邏輯來(lái)理解遠(yuǎn)程服務(wù)并與之交互。然后，文檔生成工具可以使用OpenAPI定義來(lái)顯示API，代碼生成工具可以使用各種編程語(yǔ)言來(lái)生成服務(wù)器和客戶(hù)端，測(cè)試工具以及許多其他用例也可以使用OpenAPI定義。

microprofile-open-api

此MicroProfile規(guī)范稱(chēng)為OpenAPI 1.0，旨在提供一組Java接口和編程模型，使Java開(kāi)發(fā)人員可以從其JAX-RS應(yīng)用程序本地生成OpenAPI v3文檔。

smallrye-open-api

SmallRye OpenAPI是Eclipse MicroProfile OpenAPI的具體實(shí)現(xiàn)。

綜上可知，在Quarkus中，最終使用的是smallrye-open-api。它是OpenApi v3協(xié)議Java版本的具體實(shí)現(xiàn)

集成open api

引入依賴(lài)

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

添加完以上依賴(lài)后，在開(kāi)發(fā)和測(cè)試環(huán)境會(huì)自動(dòng)激活組件，并注冊(cè)/openapi接口，通過(guò)這個(gè)接口可以獲取Openapiv3文檔，請(qǐng)求http://localhost:8080/openapi即可。同時(shí)也會(huì)注冊(cè)/swagger-ui接口，訪問(wèn)http://localhost:8080/swagger-ui就可以看到如下的界面：

默認(rèn)情況下，swagger ui只會(huì)在開(kāi)發(fā)測(cè)試環(huán)境激活，如果你想在生產(chǎn)環(huán)境也使用swagger-ui，需要在application.properties中添加quarkus.swagger-ui.always-include=true來(lái)激活，這個(gè)配置是編譯時(shí)生效的，編譯完成后無(wú)法更改。前面已經(jīng)說(shuō)過(guò)，Quarkus集成了open api導(dǎo)出接口數(shù)據(jù)使用swagger ui展示的，所有集成起來(lái)非常簡(jiǎn)單，下面看下如何使用open api的java規(guī)范注解詳細(xì)的描述接口信息

應(yīng)用基礎(chǔ)信息定義

/**
 * @author kl : http://kailing.pub
 * @version 1.0
 * @date 2020/7/14 11:29
 */
@OpenAPIDefinition(
        info = @Info(
                title = "用戶(hù)信息系統(tǒng)接口",
                version = "1.0.1",
                description = "這個(gè)信息是用來(lái)描述swagger ui接口的，你可以根據(jù)這個(gè)信息來(lái)了解這個(gè)系統(tǒng)的api情況",
                contact = @Contact(
                        name = "kl博主",
                        url = "http://www.kailing.pub",
                        email = "632104866@qq.com")
        )
)
public class SwaggerConfig extends Application {
}

openapi中使用@OpenAPIDefinition描述應(yīng)用基礎(chǔ)信息，可以類(lèi)比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 = "用戶(hù)接口列表")
public class UserResource {
    @POST
    @Path("/add")
    @Operation(summary = "創(chuàng)建用戶(hù)", description = "這是一個(gè)創(chuàng)建用戶(hù)的接口")
    public String createUser(UserDto userDto) {
        return "hello";
    }
    @POST
    @Path("/update")
    @Operation(summary = "更新用戶(hù)", description = "這是更新用戶(hù)的接口")
    public UserDto update(@RequestBody(description = "更新用戶(hù)實(shí)體", required = true,
            content = @Content(schema = @Schema(implementation = UserDto.class))) UserDto userDto) {
        return userDto;
    }
    @GET
    @Path("/{userId}")
    @Operation(summary = "查找用戶(hù)", description = "這是查找用戶(hù)的接口")
    @APIResponse(responseCode = "400", description = "找不到這個(gè)用戶(hù)")
    public UserDto findUser(@Parameter(description = "用戶(hù)的ID", required = true) @PathParam("userId") Integer userId){
        return new UserDto();
    }
    /**
     * 使用 @Operation(hidden = true) 隱藏這個(gè)api，不在swagger ui中展示
     */
    @GET
    @Path("/hello")
    @Operation(hidden = true)
    public String hello(){
        return "hello";
    }
}

效果如下：

傳輸實(shí)體定義

/**
 * @author kl : http://kailing.pub
 * @version 1.0
 * @date 2020/7/14 11:12
 */
@Schema( description = "這是一個(gè)用戶(hù)的傳輸實(shí)體")
public class UserDto {
    //隱藏內(nèi)部使用的屬性
    @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;
}

效果如下：

結(jié)語(yǔ)

在Quarkus中使用swagger ui，OpenApi v3變成了主角。swagger ui單純的變成了展示OpenApi v3數(shù)據(jù)的ui。所以使用方式上也區(qū)別了在spring環(huán)境中使用的方式，那些熟悉的swagger ui本身定義的注解都沒(méi)有了，需要重新學(xué)習(xí)microprofile-open-api中定義的注解了，好在注解變化不大，學(xué)習(xí)起來(lái)沒(méi)啥難度

以上就是Quarkus集成open api接口使用swagger ui展示的詳細(xì)內(nèi)容，更多關(guān)于Quarkus集成open api展示swagger ui的資料請(qǐng)關(guān)注腳本之家其它相關(guān)文章！

您可能感興趣的文章: