一. swagger3介绍

Swagger 3 是基于 OpenAPI 规范 3.0 的 API 文档工具，用于设计、构建和消费 RESTful API。它通过标准化描述 API 的接口、参数、响应等元数据，实现以下核心功能：

1. 自动生成交互式文档
2. API 测试与调试
3. 代码生成（客户端/服务端）
4. 多语言支持

二. Swagger3 vs Swagger 2.0

以下表格总结了Swagger 2.0和OpenAPI 3.0（Swagger 3.0）的主要差异：

OpenAPI 3.0 在以下方面进行了优化：

• 组件复用：通过 components 模块复用模型、参数、响应等，减少冗余代码。
• 多服务器配置：允许定义多个服务器环境（如开发、测试、生产），便于动态切换。
• 更丰富的参数类型：新增 cookie 参数支持，适配现代 API 需求。
• 异步支持：通过 callbacks 定义事件驱动的 API 行为。

三. 添加依赖

		// Swagger3
		<dependency>
            <groupId>org.springdoc</groupId>
            <artifactId>springdoc-openapi-starter-webmvc-ui</artifactId>
            <version>2.1.0</version>
        </dependency>

        <dependency>
            <groupId>org.springframework.boot</groupId>
            <artifactId>spring-boot-starter-validation</artifactId>
        </dependency>
	
		// Swagger2
		<dependency>
   			 <groupId>io.springfox</groupId>
    		<artifactId>springfox-swagger2</artifactId>
    		<version>2.9.2</version>
		</dependency>

		<!-- Swagger UI 依赖（可选，用于可视化界面） -->
		<dependency>
    		<groupId>io.springfox</groupId>
    		<artifactId>springfox-swagger-ui</artifactId>
   			 <version>2.9.2</version>
		</dependency>

四. 配置Swagger3

@Configuration
public class SwaggerConfig {

    @Bean
    public OpenAPI customOpenAPI() {
        return new OpenAPI()
                .info(new Info()  // 创建文档信息对象
                        .title("API 文档")   // 设置文档标题
                        .version("1.0.0")    // 设置API版本号
                        .description("项目接口文档")  // 添加详细描述
                        .contact(new Contact()  // 设置联系人信息
                                .name("还没秃顶的兔子")     // 联系人姓名
//                                .url("https://example.com")  // 联系人网址
                                .email("email@example.com"))  // 联系人邮箱
                        .license(new License()  // 设置许可证信息
                                .name("Apache 2.0")  // 许可证名称
                                .url("https://springdoc.org")));  // 许可证详情URL
    }

}

五. 接口定义

@RestController
@RequestMapping("/api")
@Tag(name = "学校管理", description = "学校管理接口")
public class SchoolsController {
	
	@Operation(summary = "添加学校", description = "创建新学校并初始化管理员账号")
    @PostMapping("/addSchools")
    private Result<Schools> addSchools(@RequestParam String name, String address) {
	}
}

http://localhost:8080/swagger-ui/index.html#/