一、Swagger简介

Swagger是一种用于设计RESTful API的规范，最早在2010年推出。随着时间的发展，Swagger逐渐形成了一个包含多种工具的生态系统，并且得到了广泛应用。2015年后，Swagger被SmartBear收购并捐赠给了Linux基金会。

二、Swagger的功能

在现代开发环境中，前后端分离已成为常态，后端负责数据处理和业务逻辑，前端则专注于用户界面和交互体验。为了确保前后端能够顺利对接，接口文档变得尤为重要。Swagger作为一款流行的API管理工具，覆盖了从设计到部署的整个API生命周期，被誉为最流行的API框架之一。

三、如何在Spring Boot中使用Swagger

1. 创建Spring Boot项目

2. 添加依赖项

<dependency>
    <groupId>io.springfox</groupId>
    <artifactId>springfox-boot-starter</artifactId>
    <version>3.0.0</version>
</dependency>

3. 配置Swagger

package com.example.swagger.config;

import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import springfox.documentation.builders.ApiInfoBuilder;
import springfox.documentation.builders.PathSelectors;
import springfox.documentation.builders.RequestHandlerSelectors;
import springfox.documentation.service.Contact;
import springfox.documentation.spi.DocumentationType;
import springfox.documentation.spring.web.plugins.Docket;

@Configuration
public class SwaggerConfig {

    @Bean
    public Docket api() {
        return new Docket(DocumentationType.OAS_30)
                .groupName("example-group")
                .apiInfo(new ApiInfoBuilder()
                        .title("示例API文档")
                        .description("这是一个关于点餐系统的API文档")
                        .contact(new Contact("示例作者", "http://example.com", "example@example.com"))
                        .version("1.0")
                        .build())
                .select()
                .apis(RequestHandlerSelectors.basePackage("com.example.swagger.controller"))
                .paths(PathSelectors.any())
                .build();
    }
}

4. 实现Swagger分组

通过创建多个Docket实例来实现不同开发者的分组：

@Bean
public Docket groupA() {
    return new Docket(DocumentationType.OAS_30).groupName("团队A");
}

@Bean
public Docket groupB() {
    return new Docket(DocumentationType.OAS_30).groupName("团队B");
}

5. 常用注解示例

实体类注解示例：

package com.example.swagger.entity;

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

@Schema(description = "书籍实体类")
public class Book {
    @Schema(description = "书名")
    private String title;

    @Schema(description = "作者")
    private String author;

    // getters and setters...
}

控制器方法注解示例：

package com.example.swagger.controller;

import io.swagger.v3.oas.annotations.Operation;
import io.swagger.v3.oas.annotations.Parameter;
import io.swagger.v3.oas.annotations.tags.Tag;
import org.springframework.web.bind.annotation.*;
import java.util.List;

@RestController
@Tag(name = "书籍模块")
public class BookController {

    @Operation(summary = "添加新书")
    @PostMapping("/books")
    public void addBook(@Parameter(description = "书籍信息") Book book) {}

    @Operation(summary = "获取所有书籍")
    @GetMapping("/books")
    public List<Book> getAllBooks() { return null; }

    // 其他方法...
}

6. 使用Swagger进行测试

启动应用后访问Swagger UI（如：http://localhost:8080/swagger-ui/index.html），可以方便地对API进行测试。