介绍

@Servers 是 Swagger/OpenAPI 3.0 注解中的一个注解，用于定义 API 的服务器信息。它属于 io.swagger.v3.oas.annotations 包，通常用于 Java 项目中，帮助生成 OpenAPI 文档。

作用

@Servers 注解用于指定 API 的服务器地址（URL），这些服务器地址可以是生产环境、测试环境、开发环境等不同的服务器。通过这个注解，你可以在生成的 OpenAPI 文档中明确列出 API 的访问地址。

源代码

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

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.TYPE, ElementType.ANNOTATION_TYPE})
@Retention(RetentionPolicy.RUNTIME)
@Inherited
public @interface Servers {
    Server[] value() default {};
}

使用场景

• 当你的 API 有多个部署环境时（如开发、测试、生产），可以使用 @Servers 注解来指定这些环境的服务器地址。

• 在生成的 OpenAPI 文档中，用户可以清楚地看到 API 的不同访问地址。

示例代码

import io.swagger.v3.oas.annotations.OpenAPIDefinition;
import io.swagger.v3.oas.annotations.info.Info;
import io.swagger.v3.oas.annotations.servers.Server;
import io.swagger.v3.oas.annotations.servers.Servers;

@OpenAPIDefinition(
    info = @Info(
        title = "demo API",
        version = "1.0.0",
        description = "这是一个demo  API"
    ),
    servers = {
        @Server(url = "https://api.chengxuyuanshitang.com", description = "生产环境"),
        @Server(url = "https://sandbox.api.chengxuyuanshitang.com", description = "测试环境")
    }
)
public class DemoApiApplication {

    public static void main(String[] args) {
        // 应用启动代码
    }
}