Quarkus:如何使用swagger-ui测试安全API端点

Quarkus 是一个用于构建高效、轻量级 Java 应用程序的框架，特别适合于云原生和微服务架构。Swagger UI 是一个流行的工具，用于可视化和测试 RESTful API。结合 Quarkus 和 Swagger UI，可以方便地测试安全 API 端点。

基础概念

Quarkus: 一个现代的、为 Kubernetes 和云原生环境优化的 Java 框架。
Swagger UI: 一个基于浏览器的界面，允许开发者直接在浏览器中与 API 进行交互。
安全 API 端点: 需要身份验证和/或授权才能访问的 API 端点。

类型

身份验证: 验证用户身份，如基本认证、OAuth2。
授权: 确定用户是否有权限执行特定操作。

应用场景

微服务架构: 在微服务环境中，API 端点通常需要安全保护。
云原生应用: 适用于 Kubernetes 和容器化环境中的应用。

如何使用 Swagger UI 测试安全 API 端点

步骤 1: 添加依赖

首先，在 pom.xml 中添加 Quarkus 和 Swagger 相关的依赖：

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

步骤 2: 配置 Swagger

在 application.properties 中配置 Swagger：

quarkus.swagger-ui.path=/swagger-ui
quarkus.smallrye-openapi.path=/openapi

步骤 3: 添加安全配置

假设使用 JWT 进行身份验证，可以在 application.properties 中添加以下配置：

quarkus.smallrye-jwt.enabled=true
mp.jwt.verify.publickey.location=publicKey.pem

步骤 4: 定义安全 API 端点

使用 JAX-RS 注解定义一个安全的 API 端点：

import javax.annotation.security.RolesAllowed;
import javax.ws.rs.GET;
import javax.ws.rs.Path;
import javax.ws.rs.core.Response;

@Path("/secure")
public class SecureResource {

    @GET
    @Path("/data")
    @RolesAllowed("user")
    public Response getData() {
        return Response.ok("Secure data").build();
    }
}

步骤 5: 访问 Swagger UI

启动 Quarkus 应用程序后，可以通过浏览器访问 Swagger UI：

http://localhost:8080/swagger-ui

在 Swagger UI 中，可以看到定义的 API 端点，并且可以输入 JWT 令牌进行身份验证。

遇到问题及解决方法

问题 1: 无法访问 Swagger UI

原因: 可能是由于端口被占用或配置错误。

解决方法: 检查 application.properties 中的端口配置，并确保没有其他应用占用该端口。

问题 2: JWT 认证失败

原因: 可能是由于 JWT 令牌无效或配置错误。

解决方法: 确保 JWT 令牌正确，并检查 application.properties 中的 JWT 配置。

示例代码

以下是一个完整的示例代码，展示了如何在 Quarkus 中配置和使用 Swagger UI 测试安全 API 端点：

import javax.annotation.security.RolesAllowed;
import javax.ws.rs.GET;
import javax.ws.rs.Path;
import javax.ws.rs.core.Response;

@Path("/secure")
public class SecureResource {

    @GET
    @Path("/data")
    @RolesAllowed("user")
    public Response getData() {
        return Response.ok("Secure data").build();
    }
}

# application.properties
quarkus.swagger-ui.path=/swagger-ui
quarkus.smallrye-openapi.path=/openapi
quarkus.smallrye-jwt.enabled=true
mp.jwt.verify.publickey.location=publicKey.pem

通过以上步骤和示例代码，可以在 Quarkus 中成功使用 Swagger UI 测试安全 API 端点。