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規(guī)范得到接口的json數(shù)據(jù)，然后使用swagger ui展示。所以在Quarkus中集成swagger ui時，會發(fā)現(xiàn)沒有swagger ui那些接口標記注解了，取而代之的是open api規(guī)范中的注解。下面來捋一捋他們的關系，看看怎么在Quarkus中使用。

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

組件關系

OpenAPI V3規(guī)范：

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

microprofile-open-api

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

smallrye-open-api

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

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

集成open api

引入依賴

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

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

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

應用基礎信息定義

/**
 * @author kl : http://kailing.pub
 * @version 1.0
 * @date 2020/7/14 11:29
 */
@OpenAPIDefinition(
        info = @Info(
                title = "用戶信息系統(tǒng)接口",
                version = "1.0.1",
                description = "這個信息是用來描述swagger ui接口的，你可以根據(jù)這個信息來了解這個系統(tǒng)的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 = "創(chuàng)建用戶", description = "這是一個創(chuàng)建用戶的接口")
    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數(shù)據(jù)的ui。所以使用方式上也區(qū)別了在spring環(huán)境中使用的方式，那些熟悉的swagger ui本身定義的注解都沒有了，需要重新學習microprofile-open-api中定義的注解了，好在注解變化不大，學習起來沒啥難度

以上就是Quarkus集成open api接口使用swagger ui展示的詳細內容，更多關于Quarkus集成open api展示swagger ui的資料請關注腳本之家其它相關文章！

您可能感興趣的文章: