OpenAPI 3 所有常用注解的实际用法

OpenAPI 3 所有常用注解的实际用法

一个完整的 Spring Boot + SpringDoc 示例，涵盖了 OpenAPI 3 所有常用注解的实际用法，包括接口分组、参数说明、响应结构、模型字段描述、隐藏接口等。

---

🧠 注解速览与用途

注解	用途
@OpenAPIDefinition	定义全局文档信息
@Tag	给接口分组
@Operation	描述接口方法
@Parameter	描述单个参数
@Parameters	批量参数描述
@RequestBody	描述请求体
@ApiResponse	描述单个响应
@ApiResponses	批量响应描述
@Schema	描述模型字段
@Hidden	隐藏接口或字段

---

✅ 示例结构：涵盖所有常用注解

📁 OpenApiConfig.java — 全局配置和分组

package com.example.config;

import io.swagger.v3.oas.annotations.OpenAPIDefinition;
import io.swagger.v3.oas.annotations.info.Info;
import io.swagger.v3.oas.annotations.info.Contact;
import io.swagger.v3.oas.annotations.info.License;
import io.swagger.v3.oas.annotations.servers.Server;
import org.springdoc.core.models.GroupedOpenApi;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;

@OpenAPIDefinition(
    info = @Info(
        title = "用户服务 API",
        description = "这是一个完整的 OpenAPI 注解示例",
        version = "v1.0",
        contact = @Contact(name = "Ning", email = "ning@example.com"),
        license = @License(name = "Apache 2.0", url = "https://www.apache.org/licenses/LICENSE-2.0")
    ),
    servers = @Server(url = "http://localhost:8080", description = "本地服务器")
)
@Configuration
public class OpenApiConfig {

    @Bean
    public GroupedOpenApi userApi() {
        return GroupedOpenApi.builder()
            .group("用户模块")
            .pathsToMatch("/api/user/**")
            .build();
    }
}

---

📁 UserController.java — 接口注解使用

package com.example.controller;

import com.example.model.User;
import io.swagger.v3.oas.annotations.Hidden;
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.tags.Tag;
import io.swagger.v3.oas.annotations.responses.ApiResponse;
import io.swagger.v3.oas.annotations.responses.ApiResponses;
import org.springframework.web.bind.annotation.*;

@Tag(name = "用户接口", description = "用户相关操作")
@RestController
@RequestMapping("/api/user")
public class UserController {

    @Operation(summary = "获取用户信息", description = "根据用户ID获取详细信息")
    @ApiResponses({
        @ApiResponse(responseCode = "200", description = "成功返回用户信息"),
        @ApiResponse(responseCode = "404", description = "用户未找到")
    })
    @GetMapping("/{id}")
    public User getUser(
        @Parameter(description = "用户ID", required = true, example = "1001")
        @PathVariable Long id
    ) {
        return new User(id, "Ning");
    }

    @Operation(summary = "创建用户", description = "提交用户信息进行创建")
    @PostMapping
    public User createUser(
        @io.swagger.v3.oas.annotations.parameters.RequestBody(
            description = "用户信息",
            required = true
        )
        @RequestBody User user
    ) {
        return user;
    }

    @Hidden
    @DeleteMapping("/{id}")
    public String deleteUser(@PathVariable Long id) {
        return "已删除用户：" + id;
    }
}

---

📁 User.java — 模型字段注解使用

package com.example.model;

import io.swagger.v3.oas.annotations.media.Schema;

@Schema(description = "用户实体类")
public class User {

    @Schema(description = "用户ID", example = "1001")
    private Long id;

    @Schema(description = "用户名", example = "Ning")
    private String name;

    // 构造方法、getter/setter 省略
}

---