掘金 后端 ( ) • 2024-03-27 18:56
玛雅!swagger3注解大全-建议收藏
Swagger3 玛雅

Swagger 3（现在称为 OpenAPI 3）是一个用于描述 RESTful API 的开源工具，它提供了一系列的注解来帮助你定义 API 的结构和文档。在 Spring Boot 项目中，你可以使用 Springdoc OpenAPI 来集成 Swagger 3。以下是一些常用的 Swagger 3 注解：

1. @OpenAPIDefinition:

用于配置 OpenAPI 定义的顶级元素，如 API 的信息、服务器、安全等。

OpenAPIDefinition 注解在 Swagger 3 中是用于定义整个 API 文档的基本信息的。Swagger 3 是基于 OpenAPI 3.0 规范的，因此 OpenAPIDefinition 注解与 OpenAPI 3.0 的规范紧密相关。

使用这个注解，你可以为 API 文档提供元数据，如标题、版本、描述、联系信息、许可信息等。这些信息对于 API 的使用者来说是非常有用的，因为它们可以帮助他们快速了解 API 的基本情况和如何正确使用。

OpenAPIDefinition 注解通常用于类或接口上，它有几个主要的属性：

  1. openapi：这是 OpenAPI 规范的版本，通常是 "3.0.x"。
  2. info：这是一个 Info 对象，用于描述 API 的基本信息，如标题、版本和描述。
  3. servers：这是一个 Server 对象的数组，描述了 API 服务器的相关信息。
  4. externalDocs：这是一个 ExternalDocumentation 对象，用于描述外部文档的位置。
  5. security：这是一个安全要求对象的数组，描述了 API 的安全需求。
  6. tags：这是一个 Tag 对象的数组，用于为 API 的操作提供分组和描述。
  7. extensions：这是一个额外的属性集合，用于提供不在 OpenAPI 规范中定义的额外信息。

下面是一个简单的示例，展示了如何使用 OpenAPIDefinition 注解：

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

@OpenAPIDefinition(
    openapi = "3.0.3",
    info = @Info(
        title = "My API", 
        version = "1.0.0", 
        description = "This is my first API using Swagger 3"
    ),
    servers = {
        @Server(url = "http://localhost:8080/api", description = "Local development server")
    }
)
public class MyApiDefinition {
    // API 的其他定义和配置
}

在这个示例中，我们定义了一个简单的 API 文档，标题为 "My API"，版本为 "1.0.0"，描述为 "This is my first API using Swagger 3"。我们还定义了一个本地开发服务器的 URL。这些信息将出现在生成的 API 文档中，帮助用户了解和使用你的 API。

2. @Info:

用于提供 API 的基本信息，如版本、标题和描述。

在 Swagger 3 中，Info 注解用于描述 API 文档的基本信息。它是 OpenAPIDefinition 注解中 info 属性的值，用于为 API 提供元数据，如标题、版本、描述等。这些信息对于 API 的使用者来说非常重要，因为它们可以帮助他们快速了解 API 的基本情况和功能。

Info 注解包含以下几个主要的属性：

  1. title：API 的标题或名称。这通常是 API 的简短描述，用于在文档中标识和区分不同的 API。
  2. version：API 的版本。这有助于区分 API 的不同迭代，并允许使用者了解他们正在使用的是哪个版本的 API。
  3. description：API 的详细描述。这可以是一个较长的文本，用于解释 API 的目的、功能、使用方式等。它是对标题和版本的补充，提供了更详细的信息。
  4. termsOfService：API 的服务条款。这是一个 URL，指向包含 API 使用条款和条件的页面。这有助于确保 API 的使用者了解并遵守相关的使用规定。
  5. contact：API 的联系信息。这可以是一个 Contact 对象，包含姓名、URL 和电子邮件地址，用于提供 API 的支持或反馈渠道。
  6. license：API 的许可信息。这是一个 License 对象，描述了 API 的许可类型（如 Apache 2.0）和许可 URL（如指向许可详细信息的页面）。
  7. extensions：额外的属性集合，用于提供不在 OpenAPI 规范中定义的额外信息。这允许你添加自定义的元数据到 API 文档中。

下面是一个使用 Info 注解的示例：

import io.swagger.v3.oas.annotations.OpenAPIDefinition;
import io.swagger.v3.oas.annotations.info.Info;
import io.swagger.v3.oas.annotations.info.License;
import io.swagger.v3.oas.annotations.info.Contact;

@OpenAPIDefinition(
    info = @Info(
        title = "My API",
        version = "1.0.0",
        description = "This is a description of my API",
        termsOfService = "http://example.com/terms",
        contact = @Contact(
            name = "API Support",
            url = "http://example.com/support",
            email = "[email protected]"
        ),
        license = @License(
            name = "Apache 2.0",
            url = "http://www.apache.org/licenses/LICENSE-2.0.html"
        )
    )
)
public class MyApiDefinition {
    // API 的其他定义和配置
}

在这个示例中，我们为 API 定义了一个标题（My API）、版本（1.0.0）和描述。我们还提供了服务条款的 URL、联系信息和许可信息。这些信息将出现在生成的 API 文档中，帮助用户了解 API 的基本情况和使用规定。

3. @Contact:

用于提供 API 维护者的联系信息。

4. @License:

用于提供 API 使用许可的相关信息。

5. @Server:

用于定义 API 的服务器信息，如 URL、描述和变量。

6. @Path:

用于指定 API 路径。

7. @Operation:

用于描述单个 API 操作（如 GET、POST、PUT、DELETE 等），包括摘要、描述、标签和外部链接。

在 Swagger 3 中，并没有直接名为 Operation 的注解。然而，你可能会想到的是 @Operation 注解，这是 OpenAPI 3.0 规范中定义的一个注解，用于描述一个具体的 API 操作或端点。在 Swagger 3 的 Java 实现中，这个注解通常用于方法上，以提供关于该方法的详细描述和元数据。

@Operation 注解允许你定义以下和其他一些属性：

  • summary：操作的简短描述。
  • description：操作的详细描述。
  • tags：与该操作相关的标签列表。
  • operationId：操作的唯一标识符，通常用于生成客户端代码。
  • parameters：操作的参数列表。
  • requestBody：操作的请求体描述。
  • responses：操作的响应描述。
  • deprecated：标记操作是否已弃用。
  • security：操作的安全要求。
  • externalDocs：外部文档的链接。

以下是一个简单的例子，展示了如何在 Swagger 3 中使用 @Operation 注解：

import io.swagger.v3.oas.annotations.Operation;
import io.swagger.v3.oas.annotations.Parameter;
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.responses.ApiResponses;
import io.swagger.v3.oas.annotations.tags.Tag;

@Tag(name = "Users")
public interface UserApi {

    @Operation(
        summary = "获取用户信息",
        description = "根据用户ID获取用户的详细信息",
        tags = {"Users"},
        operationId = "getUserById"
    )
    @ApiResponses(value = {
        @ApiResponse(
            responseCode = "200",
            description = "成功获取用户信息",
            content = @Content(
                mediaType = "application/json",
                schema = @Schema(implementation = User.class)
            )
        ),
        @ApiResponse(
            responseCode = "404",
            description = "用户未找到"
        )
    })
    User getUserById(@Parameter(description = "用户的ID") Long userId);
}

在这个例子中，我们定义了一个 UserApi 接口，其中包含一个 getUserById 方法。@Operation 注解用于描述这个方法作为一个 API 操作的具体信息，如操作的简短描述、详细描述、标签和操作ID。我们还使用了 @ApiResponses 和 @ApiResponse 注解来描述可能的响应和它们的具体内容。

请注意，Swagger 3 和 OpenAPI 3.0 提供了丰富的注解和配置选项，以便你能够精确地描述你的 API，并生成清晰、有用的文档。为了充分利用这些功能，建议查阅 Swagger 3 和 OpenAPI 3.0 的官方文档以获取更多详细信息和示例。

8. @Parameters:

用于描述 API 操作的参数。

在 Swagger 3 中，@Parameters 注解用于描述操作的输入参数，并且可以为每个参数指定详细的描述和验证规则。Swagger 3 是基于 OpenAPI 3.0 规范的，因此 @Parameters 注解与 OpenAPI 3.0 的规范紧密相关。

使用 @Parameters 注解，你可以为 RESTful API 的请求方法（如 GET、POST、PUT、DELETE 等）定义参数。这些参数可以包括路径参数、查询参数、请求头、请求体等。每个参数都可以通过注解的属性进行详细的描述，包括参数的名称、描述、是否必需、数据类型、格式等。

下面是一个简单的示例，展示了如何使用 @Parameters 注解来定义 API 的参数：

import io.swagger.v3.oas.annotations.Operation;
import io.swagger.v3.oas.annotations.Parameters;
import io.swagger.v3.oas.annotations.Parameter;
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.responses.ApiResponses;

@RestController
@RequestMapping("/api/users")
public class UserController {

    @GetMapping("/{id}")
    @Operation(summary = "获取用户信息")
    @Parameters(value = {
        @Parameter(name = "id", in = ParameterIn.PATH, description = "用户的ID", required = true, schema = @Schema(type = "integer"))
    })
    @ApiResponses(value = {
        @ApiResponse(responseCode = "200", description = "成功获取用户信息", content = @Content(schema = @Schema(implementation = User.class))),
        @ApiResponse(responseCode = "404", description = "用户未找到")
    })
    public ResponseEntity<User> getUserById(@PathVariable("id") Long id) {
        // 实现获取用户信息的逻辑
    }
}

在这个示例中，我们定义了一个 GET 请求的 /api/users/{id} 路径，用于获取指定 ID 的用户信息。@Parameters 注解用于描述这个请求的路径参数 id。我们指定了参数的名称、位置（in = ParameterIn.PATH 表示路径参数）、描述、是否必需以及数据类型。

此外，我们还使用了其他 Swagger 注解，如 @Operation 来描述整个操作，@ApiResponses 和 @ApiResponse 来描述可能的响应结果。这些注解共同构成了 API 的完整文档描述。

当 Swagger UI 或其他文档生成工具解析这些注解时，它们将生成一个可视化的 API 文档，其中包含了每个操作的参数描述、请求和响应示例等信息，从而帮助开发者更好地理解和使用 API。

9. @RequestBody:

用于描述请求体的内容，如媒体类型和示例。在 Swagger 3（OpenAPI 3）中，@RequestBody 注解是一个用于 Spring MVC 控制器中的参数的注解，它指示该参数应该绑定到 HTTP 请求体中。这个注解通常与 @PostMapping、@PutMapping、@PatchMapping 等需要接收请求体数据的注解一起使用。

@RequestBody 注解本身并不直接提供描述 API 响应或请求体内容的功能。在 Swagger 3 中，描述请求体内容通常是通过 @IO 注解库中的 @RequestBody 注解来完成的，这个注解是 Springfox 工具的一部分，用于生成 Swagger 文档。

以下是 @RequestBody 注解的一些关键属性：

  1. required (可选): 一个布尔值，指示请求体是否必须。默认值为 true。如果设置为 false，则表示请求体是可选的。
  2. description (可选): 一个字符串，提供关于请求体的描述信息。这个描述会出现在生成的 Swagger 文档中。

在 Swagger 3 中，如果你想描述请求体的结构和内容，你应该使用 @Schema 或 @Parameter 注解（取决于你使用的库）。例如，使用 Springfox 时，你可以这样使用：

@PostMapping("/users")
public ResponseEntity<?> createUser(
    @RequestBody @Valid @Schema(description = "User object to be created") UserDto userDto) {
    // ... 实现逻辑 ...
}

在这个例子中，@Schema 注解用于描述请求体的内容，提供了一个简短的描述信息。这将告诉使用 Swagger UI 的用户，他们需要发送一个 UserDto 对象作为请求体，并且这个对象是用来创建新用户的。

请注意，从 Springfox 3.x 版本开始，@RequestBody 注解不再用于描述请求体，而是使用 OpenAPI 3 规范中的注解，如 @Schema、@Parameter 等。确保你使用的库和版本支持这些注解，以便正确生成 Swagger 文档。

12. @SecurityScheme:

用于定义 API 的安全方案，如 OAuth2、API 密钥或基本认证。

在 Swagger 3（OpenAPI 3）中，@SecurityScheme 注解用于定义 API 的安全方案。这个注解允许你指定如何保护 API 的各个部分，例如使用 API 密钥、HTTP 基本认证、OAuth2 或 OpenID Connect 等。定义了安全方案后，你可以在 API 操作中引用这些方案，以指定哪些操作需要哪些类型的安全验证。

@SecurityScheme 注解通常用于配置类上，而不是单个 API 操作。这样，你可以为整个 API 或 API 的特定部分定义一个或多个安全方案。然后，你可以使用 @SecurityRequirement 注解来指定哪些安全方案适用于特定的 API 路径或操作。

以下是 @SecurityScheme 注解的一些常用属性：

  1. type (必需): 安全方案的类型。可能的值包括 "APIKEY"、"HTTP"、"OPENIDCONNECT"、"OAUTH2" 等。
  2. name (可选): 安全方案的名称。对于 API 密钥和 HTTP 基本认证，这个名称用于指定参数名（例如，"api_key" 或 "Authorization"）。
  3. in (可选): 对于 API 密钥，这个属性指定了密钥应该在请求的哪个部分发送。可能的值包括 "HEADER"、"COOKIE" 或 "QUERY"。
  4. description (可选): 安全方案的描述，提供关于如何使用该方案的详细信息。
  5. flows (可选): 对于 OAuth2 和 OpenID Connect，这个属性是一个包含授权流程详细信息的对象。它包括授权类型、授权 URL、令牌 URL、刷新令牌 URL 和作用域。

下面是一个使用 @SecurityScheme 注解的例子：

@Configuration
public class SecurityConfig {

    @Bean
    public OpenAPI securitySchema() {
        return new OpenAPI()
            .addSecurityItem(
                new SecurityScheme()
                    .name("Authorization")
                    .type(SecuritySchemeType.HTTP)
                    .scheme("bearer")
                    .bearerFormat("JWT")
                    .description("Use JWT for authorization by adding the token to the 'Authorization' header as 'Bearer {token}'")
            );
    }
}

在这个例子中，我们定义了一个基于 HTTP 的安全方案，使用 Bearer Token 方案（通常与 JWT 结合使用）。这个安全方案将在 API 文档中被引用，以指示哪些操作需要进行授权。

然后，你可以使用 @SecurityRequirement 注解来指定哪些路径或操作需要这个安全方案：

@ApiOperation(value = "Get a protected resource", security = @SecurityRequirement(name = "Authorization"))
@GetMapping("/protected-resource")
public ResponseEntity<String> getProtectedResource() {
    // ... 实现逻辑 ...
}

在这个例子中，@ApiOperation 注解的 security 属性引用了之前定义的 "Authorization" 安全方案，表明访问这个 API 操作需要有效的 Bearer Token。这样，Swagger UI 将显示一个锁图标，表示这个操作是受保护的，并且用户需要提供适当的认证信息才能访问。

13. @Tag:

用于为 API 操作添加标签，以便在文档中进行分组和过滤。

在 Swagger 3（基于 OpenAPI 3.0 规范）中，@Tag 注解用于为 API 的操作进行分组，并提供对这些组的描述。使用标签可以帮助文档的使用者更好地理解 API 的结构和功能，并使他们能够更容易地找到他们感兴趣的部分。

每个 @Tag 注解通常定义了一个标签的名称和描述。这些标签可以被附加到 API 的控制器类或方法上，以指示哪些操作属于哪个特定的组或功能区域。

以下是一些关于 @Tag 注解的关键点：

属性

  • name：标签的名称，用于在 API 文档中标识和分组操作。
  • description：对标签的描述，提供关于该组操作的额外信息。
  • externalDocs：一个 ExternalDocumentation 对象，用于提供指向外部文档的链接，这些文档可能包含有关该标签的更多详细信息。

使用示例

假设你有一个 API，其中包含处理用户信息的操作和处理订单的操作。你可以使用 @Tag 注解来区分这两组操作：

import io.swagger.v3.oas.annotations.tags.Tag;

@RestController
@RequestMapping("/users")
@Tag(name = "User Management", description = "Endpoints for managing user information")
public class UserController {
    
    // User-related endpoints here
    
}

@RestController
@RequestMapping("/orders")
@Tag(name = "Order Processing", description = "Endpoints for order placement, tracking, and management")
public class OrderController {
    
    // Order-related endpoints here
    
}

在这个例子中，UserController 类上的 @Tag 注解创建了一个名为 "User Management" 的标签，并提供了描述。同样，OrderController 类上的 @Tag 注解创建了一个名为 "Order Processing" 的标签。当 Swagger UI 或其他 API 文档工具生成文档时，这些标签将用于组织和显示相关的 API 操作。

在方法级别使用

除了在类级别使用外，@Tag 注解也可以用于方法级别，以覆盖或补充类级别的标签。这在某些情况下可能很有用，特别是当你想要为单个操作提供额外的上下文或将其归类到不同的标签组时。

注意事项

  • 如果一个操作同时被多个 @Tag 注解标记（例如在类和方法级别都有），则这些标签通常都会在生成的 API 文档中显示出来。
  • 没有明确指定标签的操作可能会继承其父类（如控制器类）上的标签。

总之，@Tag 注解在 Swagger 3 中是一个非常有用的工具，用于组织和描述 API 操作，从而使 API 文档更加清晰和易于使用。

14. @Schema:

用于定义请求和响应的数据模型，包括属性、类型和描述。

在Swagger 3中，Schema注解用于描述API的请求体和响应体的数据结构。它基于OpenAPI规范，并使用JSON Schema来定义数据模型。使用Schema注解可以将数据模型与API文档相关联，提供了一种简洁明了的方式来定义数据结构。

Schema注解可以应用于类或字段上，提供了丰富的属性来定义数据模型。以下是一些常用的Schema注解属性：

  1. name：指定模型的名称。
  2. title：指定模型的标题。
  3. description：指定模型的描述。
  4. type：指定模型的类型，如object、array、string等。
  5. required：指定模型的必需字段。
  6. example：指定模型的示例数据。

对于object类型的模型，Schema注解还提供以下属性：

  • properties：指定对象的字段。
  • additionalProperties：指定对象是否允许包含其他属性。

对于array类型的模型，Schema注解提供：

  • items：指定数组元素的类型。

对于string类型的模型，Schema注解提供：

  • format：指定字符串的格式，如date、date-time等。

通过使用这些属性，可以非常方便地定义API的请求体和响应体的数据结构，从而确保API文档的准确性和一致性。

请注意，Swagger 3的Schema注解与早期版本的Swagger（如Swagger 2）中的某些注解可能有所不同。因此，在迁移到Swagger 3时，建议仔细查阅相关文档以了解新的注解和用法。

16. @RequestBodyExample:

用于提供请求体的示例。

17. @ApiResponses和@ApiResponse:

用于描述 API 操作的可能响应，包括 HTTP 状态码、描述和示例。

用于为 API 操作定义多个响应。

在 Swagger 3（OpenAPI 3）中，@ApiResponses 注解用于定义 API 操作的可能响应。这个注解可以应用于方法上，以便为该操作的所有可能响应提供详细的描述。@ApiResponses 注解包含一个或多个 @ApiResponse 注解，每个 @ApiResponse 描述一个特定的响应状态码及其相关信息。

以下是 @ApiResponses 注解的一些关键属性：

  1. value (必需): 一个 @ApiResponse 数组，每个元素描述一个特定的响应。
  2. @ApiResponse 注解的属性：
    • responseCode (必需): HTTP 状态码，表示响应的 HTTP 状态。
    • description (必需): 对响应的简短描述。
    • content (可选): 一个 MediaType 对象数组，描述响应的内容类型（例如，JSON 或 XML）和模式（例如，使用 @Schema 引用的模型）。
    • headers (可选): 一个 Parameter 对象数组，描述响应头的信息。

下面是一个使用 @ApiResponses 注解的例子：

@ApiOperation("Get a list of users")
@ApiResponses(value = {
    @ApiResponse(responseCode = "200", description = "Successful operation"),
    @ApiResponse(responseCode = "401", description = "Unauthorized"),
    @ApiResponse(responseCode = "404", description = "Resource not found")
})
@GetMapping("/users")
public ResponseEntity<List<User>> getUsers() {
    // ... 实现逻辑 ...
}

在这个例子中，我们定义了一个 GET 请求，用于获取用户列表。我们使用了 @ApiResponses 注解来描述三个可能的响应：

  1. 状态码 200，表示操作成功。
  2. 状态码 401，表示未授权。
  3. 状态码 404，表示资源未找到。

每个 @ApiResponse 都提供了状态码和描述。这样的信息有助于 API 的使用者了解他们可以期待什么样的响应，以及每种响应的含义。此外，如果需要，你还可以为每个响应定义内容类型和响应头信息，以便提供更详细的指导。

@ApiResponses 注解是生成高质量 API 文档的关键工具之一，它使得 API 的响应更加清晰和易于理解。通过这种方式，Swagger UI 可以展示出每个 API 操作的所有可能结果，从而帮助开发者更好地测试和使用 API。

18. @Parameter:

用于描述 API 操作的查询参数或表单参数。

在 Swagger 3（OpenAPI 3）中，@Parameter 注解用于描述 API 操作的输入参数。这个注解可以应用于方法的参数上，以提供关于该参数的详细信息，这些信息将被用于生成 API 文档。@Parameter 注解提供了多种属性来定义参数的各种特性，包括名称、类型、是否必须、默认值、描述等。

以下是 @Parameter 注解的一些常用属性：

  1. name (必需): 参数的名称。这个名称将在 API 文档中显示，并与实际的参数名相对应。
  2. in (可选): 参数的位置。可以是 "query"（查询参数）、"header"、"path"、"cookie" 或 "formData"（表单数据）。
  3. description (可选): 参数的描述。这个描述将在 API 文档中显示，以帮助用户理解参数的用途和期望的值。
  4. required (可选): 布尔值，指示参数是否必须。默认为 false，即参数是可选的。
  5. deprecated (可选): 布尔值，指示参数是否已弃用。如果设置为 true，则在 API 文档中会显示该参数已弃用的标记。
  6. allowEmptyValue (可选): 布尔值，指示是否允许空值。默认为 false。
  7. schema (可选): 指定参数的模式（schema），用于描述参数的数据类型和结构。这可以用来定义复杂的数据类型，如对象或数组。
  8. example (可选): 参数的示例值。这将在 API 文档中显示，以便用户了解如何提供参数值。
  9. examples (可选): 提供多个示例值的映射，可以用来展示不同情况下的参数值。
  10. hidden (可选): 布尔值，指示参数是否在 API 文档中隐藏。默认为 false。

下面是一个使用 @Parameter 注解的例子：

@GetMapping("/users")
public ResponseEntity<List<User>> getUsers(
    @Parameter(name = "page", in = "query", description = "The page number", required = false, example = "1")
    @RequestParam Integer page,
    @Parameter(name = "size", in = "query", description = "The number of users per page", required = false, example = "10")
    @RequestParam Integer size) {
    // ... 实现逻辑 ...
}

在这个例子中，我们定义了一个 GET 请求，用于获取用户列表。我们使用了两个查询参数 page 和 size，并使用 @Parameter 注解为它们添加了描述和示例值。这些信息将被 Swagger UI 用来生成交互式的 API 文档，开发者和用户可以通过这个文档了解如何正确地使用这个 API 端点。

19. @RequestBodyDescription:

用于描述请求体的额外信息。

20. @SecurityRequirement:

用于指定 API 操作所需的安全方案和角色。

这些注解可以帮助你创建详细且易于理解的 API 文档，从而提高 API 的可维护性和可用性。使用 Springdoc OpenAPI 时，你可以通过在项目中添加相应的依赖并配置注解来生成符合 OpenAPI 3 规范的 API 文档。