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

Swagger学习⑲——@Webhook注解

article 2025/1/15 18:47:19

介绍

@Webhook 注解是 Swagger 注解库中的一个注解，用于描述 Webhook 相关的信息。

在 OpenAPI 3.0 中，Webhook 是一种机制，允许 API 提供者向订阅者发送异步通知。Webhook 通常用于事件驱动的架构中，当某个事件发生时，API 提供者会向订阅者的指定 URL 发送一个 HTTP 请求。

参考文档

Swagger 3.0 Webhook 注解文档
Swagger 3.0 注解使用示例

源代码

package io.swagger.v3.oas.annotations;

import java.lang.annotation.ElementType;
import java.lang.annotation.Inherited;
import java.lang.annotation.Retention;
import java.lang.annotation.RetentionPolicy;
import java.lang.annotation.Target;

@Target({ElementType.METHOD, ElementType.ANNOTATION_TYPE})
@Retention(RetentionPolicy.RUNTIME)
@Inherited
@OpenAPI31
public @interface Webhook {
    String name();

    Operation operation();
}

属性

name：Webhook 的名称，用于标识该 Webhook。
operation：定义 Webhook 触发时的具体操作，使用 @Operation 注解来描述。

示例代码

import io.swagger.v3.oas.annotations.OpenAPIDefinition;
import io.swagger.v3.oas.annotations.Operation;
import io.swagger.v3.oas.annotations.Parameter;
import io.swagger.v3.oas.annotations.info.Info;
import io.swagger.v3.oas.annotations.media.Content;
import io.swagger.v3.oas.annotations.media.Schema;
import io.swagger.v3.oas.annotations.responses.ApiResponse;
import io.swagger.v3.oas.annotations.tags.Tag;
import io.swagger.v3.oas.annotations.webhooks.Webhook;
import io.swagger.v3.oas.annotations.webhooks.Webhooks;

@OpenAPIDefinition(
    info = @Info(
        title = "Webhook Example API",
        version = "1.0",
        description = "API demonstrating the use of Webhook annotations"
    ),
    webhooks = {
        @Webhook(
            name = "demoCreated",
            description = "创建新demo时触发Webhook",
            operation = @Operation(
                summary = "demo Created Webhook",
                description = "创建新demo时会触发此webhook.",
                responses = {
                    @ApiResponse(
                        responseCode = "200",
                        description = "Webhook received successfully",
                        content = @Content(
                            mediaType = "application/json",
                            schema = @Schema(implementation = Order.class)
                        )
                    )
                }
            )
        )
    }
)
public class WebhookExampleApi {

    //此处为您的API实现
}