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

Swagger学习⑰——@Link注解

article 2025/1/13 3:10:04

介绍

@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 
    }
}