当前位置：首页 > article >正文

Swagger学习⑱——@Callback 注解

article 2025/1/13 2:27:06

介绍

@Callback 是 Swagger/OpenAPI 3.0 注解库中的一个注解，用于在 OpenAPI 文档中定义回调（Callback）。回调是一种描述异步操作的机制，通常用于 Webhook 或事件驱动的 API 场景。

`@Callback` 注解的作用

@Callback 注解用于在 OpenAPI 文档中定义一个回调操作。回调通常用于以下场景：

Webhook：当某个事件发生时，API 服务器会向客户端发送一个 HTTP 请求。
异步操作：当某个操作需要较长时间完成时，API 服务器会在完成后通知客户端。
事件驱动架构：描述 API 如何响应外部事件。

源代码

package io.swagger.v3.oas.annotations.callbacks;

import io.swagger.v3.oas.annotations.Operation;
import io.swagger.v3.oas.annotations.extensions.Extension;
import java.lang.annotation.ElementType;
import java.lang.annotation.Inherited;
import java.lang.annotation.Repeatable;
import java.lang.annotation.Retention;
import java.lang.annotation.RetentionPolicy;
import java.lang.annotation.Target;

@Target({ElementType.FIELD, ElementType.METHOD, ElementType.PARAMETER, ElementType.TYPE, ElementType.ANNOTATION_TYPE})
@Retention(RetentionPolicy.RUNTIME)
@Repeatable(Callbacks.class)
@Inherited
public @interface Callback {
    String name() default "";

    String callbackUrlExpression() default "";

    Operation[] operation() default {};

    Extension[] extensions() default {};

    String ref() default "";
}

`@Callback` 注解的属性

@Callback 注解的主要属性如下：

属性名	类型	描述
`name`	`String`	回调的名称，必须是唯一的。
`operation`	`Operation`	回调的操作定义。
`ref`	`String`	引用外部定义的回调。
`callbackUrlExpression`	`String`	回调 URL 的表达式，用于动态生成回调 URL。

示例代码

定义回调

以下是一个使用 @Callback 注解的示例，展示如何在 API 中定义回调：

import io.swagger.v3.oas.annotations.Operation;
import io.swagger.v3.oas.annotations.callbacks.Callback;
import io.swagger.v3.oas.annotations.callbacks.Callbacks;
import io.swagger.v3.oas.annotations.responses.ApiResponse;
import io.swagger.v3.oas.annotations.responses.ApiResponses;
import io.swagger.v3.oas.annotations.media.Content;
import io.swagger.v3.oas.annotations.media.Schema;

@RestController
public class DemoController {

    @Operation(summary = "Create an Demo", description = "Create a new Demo and register a callback for status updates")
    @Callbacks({
        @Callback(
            name = "demoStatusCallback",
            operation = @Operation(
                summary = "Callback for Demo status updates",
                responses = {
                    @ApiResponse(
                        responseCode = "200",
                        description = "Callback received successfully",
                        content = @Content(mediaType = "application/json", schema = @Schema(implementation = DemoStatus.class))
                    )
                }
            ),
            callbackUrlExpression = "http://chengxuyuanshitang.com/demo-status/{$request.body#demoId}"
        )
    })
    @PostMapping("/demos")
    public void createDemo(@RequestBody Demo  demo) {
        // 创建订单并注册回调
    }
}