【quarkus系列】Quarkus整合openapi之swagger

官网指南：使用 OpenAPI 和 Swagger UI - Quarkus — Using OpenAPI and Swagger UI - Quarkus

回顾

Quarkus入门项目启动完成之后，可以进入Quarkus DEV UI页面，如果没有了解的小伙伴，请移步【quarkus系列】创建quarkus第一个应用程序
此时没有引入swagger组件如下：

添加项目依赖

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

正常启动项目：

明显可以看到swagger的地址，点击便可以直接进入swagger-ui进行调试接口，是不是很方便呀~

实践

Quarkus也支持修改swagger访问路径

• application.properties

quarkus.swagger-ui.path=/swagger

• Controller代码

@Path("/book")
@Produces(MediaType.APPLICATION_JSON)
@Consumes(MediaType.APPLICATION_JSON)
@Tag(name = "Book Resource", description = "Operations related to books")
@OpenAPIDefinition(info = @Info(title = "Book API", version = "1.0", description = "API for managing books"))
public class BookResource {

    @GET
    @Operation(summary = "Get all books",
            description = "Returns all books in the library.")
    @APIResponse(responseCode = "200",
            description = "List of all books",
            content = @Content(mediaType = MediaType.APPLICATION_JSON,
            schema = @Schema(implementation = Book.class, type = SchemaType.ARRAY)))
    public Book[] getAll() {
        // return all books
        return null;
    }

    @POST
    @Operation(summary = "Create a book",
            description = "Create a new book in the library.")
    @APIResponse(responseCode = "201",
            description = "The book was created successfully.")
    public void create(@RequestBody(description = "The book to create.", required = true, content = @Content(schema = @Schema(implementation = Book.class))) Book book) {
        // create a new book
    }
}


@Schema(description="Book entity that represents a book in the library.")
@AllArgsConstructor
@NoArgsConstructor
@Data
public class Book {

    @Schema(required = true, description = "The unique identifier of the book.")
    private Long id;

    @Schema(required = true, description = "The title of the book.")
    private String title;

    @Schema(required = true, description = "The author of the book.")
    private String author;
}

请求如图所示：

• @OpenAPIDefinition: 用于定义API的一般信息，如标题、版本、描述等。在这个例子中，它定义了API的标题为"Book API"，版本为"1.0"，描述为"Book API"。
• @Tag: 用于对API进行分类。
• @Operation: 用于描述一个HTTP操作。在这个例子中，它描述了两个操作：“Get all books"和"Create a book”。
• @APIResponse: 用于描述一个HTTP响应。在这个例子中，它描述了"Get all books"操作的200响应和"Create a book"操作的201和400响应。
• @APIResponses: 用于描述多个HTTP响应。在这个例子中，它描述了"Create a book"操作的201和400响应。
• @RequestBody: 用于描述一个HTTP请求体。在这个例子中，它描述了"Create a book"操作的请求体。
• @Schema: 用于描述一个模型的结构。在这个例子中，它描述了Book模型的结构。
• @Parameter: 用于描述一个HTTP请求参数。