SpringBoot集成Swagger 2

在 Spring Boot 中，使用 Swagger 2 可以非常方便地构建和测试 RESTful APIs。Swagger 提供了交互式的 API 文档页面，使开发者和用户能够直观地了解和使用 API。

以下是如何在 Spring Boot 中集成 Swagger 2 的详细步骤。

---

1. 添加 Maven 依赖

在项目的 pom.xml 中添加 Swagger 相关依赖：

<dependencies>
    <!-- Swagger 依赖 -->
    <dependency>
        <groupId>io.springfox</groupId>
        <artifactId>springfox-boot-starter</artifactId>
        <version>3.0.0</version> <!-- 确保版本兼容 -->
    </dependency>
</dependencies>

如果使用 Gradle，添加：

implementation 'io.springfox:springfox-boot-starter:3.0.0'

---

2. 配置 Swagger

创建一个配置类，用于初始化 Swagger 2：

import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import springfox.documentation.builders.PathSelectors;
import springfox.documentation.builders.RequestHandlerSelectors;
import springfox.documentation.spi.DocumentationType;
import springfox.documentation.spring.web.plugins.Docket;
​
@Configuration
public class SwaggerConfig {
​
    @Bean
    public Docket api() {
        return new Docket(DocumentationType.SWAGGER_2)
                .select()
                // 扫描指定的包路径
                .apis(RequestHandlerSelectors.basePackage("com.example.controller"))
                .paths(PathSelectors.any()) // 匹配所有路径
                .build();
    }
}

---

3. 编写 RESTful API

创建一个简单的 Controller 测试 Swagger 的效果：

package com.example.controller;
​
import org.springframework.web.bind.annotation.*;
​
@RestController
@RequestMapping("/api/v1")
public class UserController {
​
    @GetMapping("/users")
    public String getUsers() {
        return "List of users";
    }
​
    @PostMapping("/users")
    public String createUser(@RequestBody String user) {
        return "User created: " + user;
    }
​
    @GetMapping("/users/{id}")
    public String getUserById(@PathVariable String id) {
        return "User with ID: " + id;
    }
​
    @DeleteMapping("/users/{id}")
    public String deleteUser(@PathVariable String id) {
        return "User deleted with ID: " + id;
    }
}

---

4. 访问 Swagger UI

启动 Spring Boot 应用后，访问以下 URL：

• Swagger UI 页面： http://localhost:8080/swagger-ui/

注意： 默认情况下，Swagger UI 会根据配置类扫描并生成文档页面，展示所有 RESTful API 的详细信息和接口调用示例。

---

5. 示例文档页面

Swagger 页面会根据 UserController 自动生成如下 API 文档：

• GET /api/v1/users

• POST /api/v1/users

• GET /api/v1/users/{id}

• DELETE /api/v1/users/{id}

通过页面可以直接发送请求并查看响应。

---

6. 其他 Swagger 配置项

全局 API 信息

在 SwaggerConfig 中，可以设置全局的 API 信息，比如标题、版本、描述等：

import springfox.documentation.service.ApiInfo;
import springfox.documentation.service.Contact;
import springfox.documentation.spi.DocumentationType;
import springfox.documentation.spring.web.plugins.Docket;
import springfox.documentation.builders.ApiInfoBuilder;
​
@Bean
public Docket api() {
    return new Docket(DocumentationType.SWAGGER_2)
            .select()
            .apis(RequestHandlerSelectors.any())
            .paths(PathSelectors.any())
            .build()
            .apiInfo(apiInfo());
}
​
private ApiInfo apiInfo() {
    return new ApiInfoBuilder()
            .title("My RESTful API")
            .description("This is a sample API documentation using Swagger2")
            .version("1.0")
            .contact(new Contact("Your Name", "https://example.com", "email@example.com"))
            .build();
}

隐藏或忽略某些 API

• 对于 Controller 或 API 方法，可以使用注解 @ApiIgnore 来隐藏不希望暴露的接口。

import springfox.documentation.annotations.ApiIgnore;
​
@ApiIgnore
@RestController
public class HiddenController {
    // 这个类不会在 Swagger 文档中显示
}

---

7. 整合 Spring Security（可选）

如果项目中启用了 Spring Security，需要为 Swagger UI 相关资源路径配置放行：

@Override
protected void configure(HttpSecurity http) throws Exception {
    http.authorizeRequests()
        .antMatchers("/swagger-ui/**", "/v2/api-docs", "/swagger-resources/**", "/webjars/**").permitAll()
        .anyRequest().authenticated();
}

总结

通过集成 Swagger 2，开发者可以直观地管理和测试 RESTful APIs，主要步骤包括：

1. 添加依赖。

2. 配置 SwaggerConfig。

3. 编写 Controller。

4. 访问 Swagger UI 测试接口。

这种方式特别适合团队协作，便于前后端联调和文档维护。