Spring Boot 集成 Swagger 进行接口文档生成：如何让你的 API 文档与代码完美同步？

🏆本文收录于「滚雪球学SpringBoot」专栏(全网一个名)，手把手带你零基础入门Spring Boot，从入门到就业，助你早日登顶实现财富自由🚀；同时，欢迎大家关注&&收藏&&订阅！持续更新中，up！up！up！！

环境说明：Windows 10 + IntelliJ IDEA 2021.3.2 + Jdk 1.8

前言：

在构建和维护 Web API 时，接口文档的生成是非常重要的一环。对于开发者和使用者来说，准确、详细的 API 文档能够极大地提升协作效率和项目可维护性。我们常常需要一个自动化的方式来生成接口文档，以确保代码与文档同步更新，避免人工维护文档带来的不一致问题。

Swagger 是一个非常流行的 API 文档生成工具，它能够通过注解的方式自动生成接口文档，并且支持多种展示方式。在 Spring Boot 项目中集成 Swagger 非常简单，并且可以定制化地生成符合需求的 API 文档，甚至为接口文档提供权限控制。

本文将详细介绍如何在 Spring Boot 中集成 Swagger，如何使用 Swagger 提供的注解生成接口文档，并且介绍如何配置 Swagger UI、定制文档内容、以及进行接口文档的权限控制。准备好了吗？让我们开始吧！🚀

🔍 Swagger 简介与集成

1. Swagger 简介

Swagger 是一款开源的 API 文档生成工具，它为开发者提供了一个简洁的方式来描述 RESTful API。通过 Swagger，开发者不仅可以自动生成接口文档，还可以通过 Swagger UI 提供一个交互式的文档界面，用户可以直接在页面上执行 API 请求，查看请求和响应的具体信息。

Swagger 生成的文档是标准化的，能够清晰地显示 API 的路径、请求参数、响应信息、错误代码等内容。它的优势在于能够快速与代码同步更新，避免了手动维护文档的烦恼。

2. 集成 Swagger

在 Spring Boot 项目中集成 Swagger 主要依赖于 springfox-swagger2 和 springfox-swagger-ui 这两个依赖。我们可以通过 Maven 或 Gradle 来添加相关依赖。

Maven 配置

<dependencies>
    <!-- Swagger 2 -->
    <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>
</dependencies>

Gradle 配置

dependencies {
    // Swagger 2
    implementation 'io.springfox:springfox-swagger2:2.9.2'
    // Swagger UI
    implementation 'io.springfox:springfox-swagger-ui:2.9.2'
}

通过添加这些依赖，Swagger 就可以与 Spring Boot 项目进行集成，自动生成接口文档。

3. 配置 Swagger

在 Spring Boot 中，我们需要通过配置类启用 Swagger。通常，我们会创建一个配置类来初始化 Swagger 相关的配置。

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.spi.DocumentationType;
import springfox.documentation.spring.web.plugins.Docket;
import springfox.documentation.swagger2.annotations.EnableSwagger2;

@Configuration
@EnableSwagger2
public class SwaggerConfig {

    @Bean
    public Docket api() {
        return new Docket(DocumentationType.SWAGGER_2)
                .select()
                .apis(RequestHandlerSelectors.basePackage("com.example.demo.controller"))
                .paths(PathSelectors.any())
                .build()
                .apiInfo(new ApiInfoBuilder()
                        .title("Spring Boot Swagger API")
                        .description("This is a sample API documentation using Swagger")
                        .version("1.0")
                        .build());
    }
}

在这个配置类中，我们使用 @EnableSwagger2 启用了 Swagger，配置了 API 的基本信息，并通过 Docket 定义了哪些控制器和路径需要被扫描以生成文档。

📑 使用 @Api 和 @ApiOperation 注解

Swagger 通过注解来生成 API 文档，@Api 和 @ApiOperation 是最常用的两个注解。通过这两个注解，我们可以为每个控制器和方法提供详细的描述。

1. @Api 注解

@Api 注解通常用于标注控制器类，描述控制器的作用和功能。它可以接受以下属性：

• value：控制器的描述，通常是控制器的功能或用途。
• tags：给控制器添加标签，方便分组和分类。

import io.swagger.annotations.Api;
import org.springframework.web.bind.annotation.RestController;

@Api(value = "User Management Controller", tags = {"User Management"})
@RestController
public class UserController {

    // 控制器方法
}

2. @ApiOperation 注解

@ApiOperation 注解用于描述控制器方法，它可以提供更多关于某个 API 接口的详细信息，如接口的功能、请求方式等。

import io.swagger.annotations.ApiOperation;
import org.springframework.web.bind.annotation.GetMapping;
import org.springframework.web.bind.annotation.PathVariable;
import org.springframework.web.bind.annotation.RequestMapping;

@ApiOperation(value = "Get User by ID", notes = "Fetches a user by their unique ID")
@RequestMapping("/users")
public String getUserById(@PathVariable Long id) {
    return "User: " + id;
}

3. 完整的控制器示例

import io.swagger.annotations.Api;
import io.swagger.annotations.ApiOperation;
import org.springframework.web.bind.annotation.GetMapping;
import org.springframework.web.bind.annotation.PathVariable;
import org.springframework.web.bind.annotation.RestController;

@Api(value = "User Management Controller", tags = {"User Management"})
@RestController
@RequestMapping("/users")
public class UserController {

    @ApiOperation(value = "Get User by ID", notes = "Fetches a user by their unique ID")
    @GetMapping("/{id}")
    public String getUserById(@PathVariable Long id) {
        return "User: " + id;
    }
}

通过这些注解，我们可以为每个接口提供详细的文档描述，生成更加人性化、易懂的 API 文档。

🌐 配置 Swagger UI 界面

Swagger 提供了一个直观、交互式的 UI 界面，帮助我们更好地展示 API 文档并进行接口调试。Spring Boot 集成 Swagger 后，可以通过访问特定的 URL 来查看 Swagger UI 界面。

1. 启动 Swagger UI

Swagger UI 默认会映射到 /swagger-ui.html，你只需要在浏览器中访问该路径，即可查看接口文档。例如：

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

这将打开一个交互式的界面，你可以在其中查看所有的 API 接口，并直接测试接口的请求和响应。

2. 自定义 Swagger UI 配置

你可以通过修改 application.properties 或 application.yml 文件来定制 Swagger UI 的行为。例如，修改默认路径或设置文档信息：

swagger.ui.path=/api-docs

这样，Swagger UI 将会在 /api-docs 路径下提供文档。

✨ 自定义文档内容与格式

Spring Boot 集成 Swagger 后，生成的文档内容是非常基础的，但在实际开发中，我们往往需要自定义一些内容，如文档信息、接口参数描述、返回值说明等。

1. 自定义 API 信息

通过 ApiInfo 类，你可以轻松自定义文档的元数据，包括标题、描述、版本等：

import springfox.documentation.service.ApiInfo;
import springfox.documentation.service.Contact;

@Bean
public Docket api() {
    return new Docket(DocumentationType.SWAGGER_2)
            .select()
            .apis(RequestHandlerSelectors.basePackage("com.example.demo"))
            .paths(PathSelectors.any())
            .build()
            .apiInfo(apiInfo());
}

private ApiInfo apiInfo() {
    return new ApiInfo(
            "My API",
            "This is a sample API documentation",
            "1.0",
            "Terms of service",
            new Contact("Developer", "www.example.com", "developer@example.com"),
            "License of API",
            "API license URL",
            Collections.emptyList());
}

2. 自定义请求参数与响应

你可以使用 @ApiParam 注解为方法参数提供详细描述，使用 @ApiResponse 注解来描述 API 响应。

@ApiOperation(value = "Create User", notes = "Creates a new user")
@PostMapping("/create")
public ResponseEntity<User> createUser(@ApiParam(value = "User object to be created", required = true) @RequestBody User user) {
    // Create user logic
    return ResponseEntity.ok(newUser);
}

这样生成的文档将更加详细，并且能够清晰地描述接口的输入输出内容。

🔒 接口文档的权限控制

在实际的生产环境中，我们通常需要对 API 文档进行权限控制，确保只有特定的用户或角色才能访问接口文档。Swagger 提供了简单的权限控制机制，通过 Spring Security 来实现。

1. 配置 Spring Security

你可以通过 Spring Security 来限制访问 Swagger 文档的权限。例如，允许仅管理员访问：

@EnableWebSecurity
public class SecurityConfig extends WebSecurityConfigurerAdapter {

    @Override
    protected void configure(HttpSecurity http) throws Exception {
        http.authorizeRequests()
            .antMatchers("/swagger-ui.html**").hasRole("ADMIN")  // 仅管理员可访问
            .antMatchers("/**").permitAll()
            .and().formLogin();
    }
}

2. 配置 Swagger 路径的权限

如果你希望在生产环境中隐藏 Swagger UI，可以通过修改配置来禁用 Swagger 路径：

@Configuration
public class SwaggerConfig {
    @Bean
    public Docket api() {
        return new Docket(DocumentationType.SWAGGER_2)
                .select()
                .apis(RequestHandlerSelectors.basePackage("com.example.demo"))
                .paths(PathSelectors.any())
                .build()
                .apiInfo(new ApiInfoBuilder()
                        .title("API Documentation")
                        .description("Description of APIs")
                        .version("1.0")
                        .build())
                .enable(false);  // 禁用 Swagger UI
    }
}

通过这种方式，你可以根据不同的环境控制 Swagger 文档的展示。

结语：

通过本篇文章的学习，相信你已经掌握了如何在 Spring Boot 中集成 Swagger，如何使用注解生成接口文档，如何定制文档内容，以及如何对接口文档进行权限控制。Swagger 不仅是一个强大的 API 文档工具，它还可以帮助开发者更好地理解和使用接口，提高开发效率和应用的可维护性。

希望这篇文章能帮助你在项目中实现高质量的 API 文档，提升团队的协作效率和项目的可维护性。记住，好的文档是开发过程中的一部分，它不仅能提高代码的可读性，也能增强与其他团队成员和客户端的沟通！📚✨

🧧福利赠与你🧧

  无论你是计算机专业的学生，还是对编程有兴趣的小伙伴，都建议直接毫无顾忌的学习此专栏「滚雪球学SpringBoot」专栏(全网一个名)，bug菌郑重承诺，凡是学习此专栏的同学，均能获取到所需的知识和技能，全网最快速入门SpringBoot，就像滚雪球一样，越滚越大， 无边无际，指数级提升。

  最后，如果这篇文章对你有所帮助，帮忙给作者来个一键三连，关注、点赞、收藏，您的支持就是我坚持写作最大的动力。

  同时欢迎大家关注公众号:「猿圈奇妙屋」 ，以便学习更多同类型的技术文章，免费白嫖最新BAT互联网公司面试题、4000G pdf电子书籍、简历模板、技术文章Markdown文档等海量资料。

✨️ Who am I?

我是bug菌(全网一个名)，CSDN | 掘金 | InfoQ | 51CTO | 华为云 | 阿里云 | 腾讯云 等社区博客专家，C站博客之星Top30，华为云多年度十佳博主/价值贡献奖，掘金多年度人气作者Top40，掘金等各大社区平台签约作者，51CTO年度博主Top12，掘金/InfoQ/51CTO等社区优质创作者；全网粉丝合计 30w+；更多精彩福利点击这里；硬核微信公众号「猿圈奇妙屋」，欢迎你的加入！免费白嫖最新BAT互联网公司面试真题、4000G PDF电子书籍、简历模板等海量资料，你想要的我都有，关键是你不来拿。

-End-