介绍

@Link 是 Swagger/OpenAPI 3.0 注解库中的一个注解，用于在 OpenAPI 文档中定义链接（Link）。链接是一种在 API 响应中提供相关操作或资源引用的机制，通常用于描述操作之间的关系或提供额外的操作提示。

 @Link 注解的作用

@Link 注解用于在 OpenAPI 文档中定义一个链接，它可以关联到某个操作（Operation）或资源。链接通常用于以下场景：

• 描述操作之间的关系（例如，创建资源后返回的资源链接）。

• 提供额外的操作提示（例如，分页查询中的下一页链接）。

• 实现 HATEOAS（Hypermedia as the Engine of Application State）风格的 API。

源代码

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

import io.swagger.v3.oas.annotations.extensions.Extension;
import io.swagger.v3.oas.annotations.servers.Server;
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.ANNOTATION_TYPE})
@Retention(RetentionPolicy.RUNTIME)
@Inherited
public @interface Link {
    String name() default "";

    String operationRef() default "";

    String operationId() default "";

    LinkParameter[] parameters() default {};

    String description() default "";

    String requestBody() default "";

    Server server() default @Server;

    Extension[] extensions() default {};

    String ref() default "";
}

@Link 注解的属性

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

属性名	类型	描述
name	String	链接的名称，必须是唯一的。
operationId	String	链接指向的操作的 operationId。
operationRef	String	链接指向的操作的引用（URL 或路径）。
description	String	链接的描述信息。
requestBody	String	链接指向的操作的请求体表达式。
parameters	Parameter	链接指向的操作的参数映射。
server	Server	链接指向的服务器的配置。
ref	String	引用外部定义的链接。

---

示例代码

import io.swagger.v3.oas.annotations.Operation;
import io.swagger.v3.oas.annotations.links.Link;
import io.swagger.v3.oas.annotations.links.LinkParameter;
import io.swagger.v3.oas.annotations.responses.ApiResponse;
import io.swagger.v3.oas.annotations.responses.ApiResponses;

@RestController
public class DemoController {

    @Operation(summary = "Get Demo by ID", operationId = "getDemoById")
    @ApiResponses(value = {
        @ApiResponse(
            responseCode = "200",
            description = "Demo found",
            links = {
                @Link(
                    name = "updateDemo ",
                    operationId = "updateDemo",
                    parameters = @LinkParameter(name = "demoId", expression = "$response.body#id")
                ),
                @Link(
                    name = "deleteDemo",
                    operationId = "deleteDemo",
                    parameters = @LinkParameter(name = "demoId", expression = "$response.body#id")
                )
            }
        )
    })
    @GetMapping("/demo/{id}")
    public User getDemoById(@PathVariable Long id) {
        // 返回Demo 信息
        return new User(id, "demo Doe");
    }

    @Operation(summary = "Update demo by ID", operationId = "updateDemo")
    @PutMapping("/demo/{id}")
    public void updateDemo(@PathVariable Long id, @RequestBody Demo user) {
        // 更新Demo 信息
    }

    @Operation(summary = "Delete demo by ID", operationId = "deleteDemo")
    @DeleteMapping("/demo/{id}")
    public void deleteDemo(@PathVariable Long id) {
        // 删除Demo 
    }
}

---

---

---