如何在Quarkus Rest API调用中使用YAML中的对象参数？

1. Swagger UI直接调用时复用示例值 #

Quarkus集成的Swagger UI（默认访问路径/q/swagger-ui）会自动读取OpenAPI YAML中定义的example或examples字段，在API调用界面直接提供示例参数：

• 在YAML中给请求体对象配置示例：

components:
  schemas:
    UserRequest:
      type: object
      properties:
        username:
          type: string
          example: "john_doe"
        email:
          type: string
          example: "john@example.com"
      required: [username, email]
paths:
  /api/users:
    post:
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UserRequest'

• 启动Quarkus服务后，打开/q/swagger-ui找到对应接口，点击「Try it out」，请求体区域会自动填充你定义的示例值，直接发送请求即可。

2. 代码中加载YAML示例值作为输入 #

如果需要在业务或测试代码里复用这些示例值，可通过SmallRye OpenAPI的API读取OpenAPI模型：

• 注入OpenAPIModelReader加载文档并提取示例：

import io.smallrye.openapi.api.OpenAPIModelReader;
import org.eclipse.microprofile.openapi.models.OpenAPI;
import org.eclipse.microprofile.openapi.models.media.Schema;
import com.fasterxml.jackson.databind.ObjectMapper;
import jakarta.inject.Inject;
import jakarta.enterprise.context.ApplicationScoped;

@ApplicationScoped
public class ExampleLoader {

    @Inject
    OpenAPIModelReader modelReader;
    private final ObjectMapper objectMapper = new ObjectMapper();

    public String getUserRequestExample() throws Exception {
        OpenAPI openAPI = modelReader.read();
        Schema<?> userSchema = openAPI.getComponents().getSchemas().get("UserRequest");
        Object exampleObj = userSchema.getExample();
        return objectMapper.writeValueAsString(exampleObj);
    }
}

• 调用该方法即可拿到示例JSON字符串，直接作为API请求参数使用。

3. 给单个接口单独指定示例 #

若不需要给整个Schema绑定示例，也可直接在接口的请求体中定义专属示例：

paths:
  /api/users:
    post:
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UserRequest'
            example:
              username: "jane_smith"
              email: "jane@example.com"

这种方式的示例仅作用于当前接口，不会影响其他引用该Schema的接口。

内容的提问来源于stack exchange，提问作者shrmz