Swagger学习⑧——@Parameters注解

介绍

@Parameters 注解是 Swagger Core 库的一部分，属于 Swagger/OpenAPI 3.x。它用于在 API 操作中同时描述多个参数。与 @Parameter 注解不同，@Parameters 是一个容器注解，可以包含多个 @Parameter 注解，从而更简洁地描述多个参数。

作用

@Parameters 注解的主要作用是将多个 @Parameter 注解组合在一起，方便在一个方法中描述多个参数。它通常用于以下场景：

• 当一个 API 操作需要多个参数时，可以使用 @Parameters 来集中管理这些参数的元数据。

• 提高代码的可读性和可维护性。

源代码

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
public @interface Parameters {
    Parameter[] value() default {};
}

示例代码

import io.swagger.v3.oas.annotations.Operation;
import io.swagger.v3.oas.annotations.Parameter;
import io.swagger.v3.oas.annotations.Parameters;
import io.swagger.v3.oas.annotations.enums.ParameterIn;
import io.swagger.v3.oas.annotations.responses.ApiResponse;
import io.swagger.v3.oas.annotations.tags.Tag;
import org.springframework.web.bind.annotation.*;

@RestController
@RequestMapping("/api")
@Tag(name = "Demo管理", description = "Demo相关的 API")
public class DemoController {

    @Operation(
        summary = "搜索Demo",
        description = "根据多个条件搜索Demo",
        responses = {
            @ApiResponse(responseCode = "200", description = "成功搜索到Demo")
        }
    )
    @Parameters({
        @Parameter(
            name = "name",
            description = "Demo名",
            required = false,
            example = "John",
            in = ParameterIn.QUERY
        ),
        @Parameter(
            name = "info",
            description = "Demo info",
            required = false,
            example = "25",
            in = ParameterIn.QUERY
        ),
        @Parameter(
            name = "city",
            description = "Demo所在城市",
            required = false,
            example = "New York",
            in = ParameterIn.QUERY
        )
    })
    @GetMapping("/demos/search")
    public String searchDemors(
        @RequestParam(required = false) String name,
        @RequestParam(required = false) Integer info,
        @RequestParam(required = false) String city) {
        return "Searching for Demo with name: " + name + ", info: " + info + ", city: " + city;
    }
}