Spring Boot 中 Swagger 配置详解：生成高效的 RESTful API 文档

        在项目开发中，清晰的 API 文档对前后端协作至关重要。而 Swagger 是一个强大的工具，它不仅能生成 RESTful API 文档，还提供了交互界面，方便开发人员进行接口测试。本篇文章将以一个完整示例为基础，讲解如何在 Spring Boot 中配置 Swagger，并支持 JWT 认证的 API 调用。

一、Swagger 的功能简介

Swagger 是什么？

Swagger 是一种 RESTful API 文档生成工具，常与 Spring Boot 结合使用。它能自动扫描代码中的 API 接口，并生成一份包含接口描述、请求方式、参数、响应示例等内容的文档。

Swagger 的主要优势：

1. 自动生成文档，节省维护成本。

2. 提供交互式界面，方便开发者调试接口。

3. 支持参数校验、认证等功能扩展。

---

二、Spring Boot 中的 Swagger 配置

以下是一个完整的 Swagger 配置类，展示了从基础到高级功能的实现。

package com.example.emos.wx.api.config;



import io.swagger.annotations.ApiOperation;

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.ApiInfo;

import springfox.documentation.service.ApiKey;

import springfox.documentation.service.AuthorizationScope;

import springfox.documentation.service.SecurityReference;

import springfox.documentation.spi.DocumentationType;

import springfox.documentation.spi.service.contexts.SecurityContext;

import springfox.documentation.spring.web.plugins.Docket;

import springfox.documentation.swagger2.annotations.EnableSwagger2;



import java.util.ArrayList;

import java.util.List;



/**

Swagger 配置类，生成 RESTful API 文档。

*/

@Configuration

@EnableSwagger2 // 启用 Swagger

public class SwaggerConfig {



@Bean

public Docket createRestApi() {

// 创建 Docket 实例，定义文档类型为 SWAGGER_2

Docket docket = new Docket(DocumentationType.SWAGGER_2);



// 配置 API 的基本信息

ApiInfoBuilder builder = new ApiInfoBuilder();

builder.title("EMOS在线办公系统"); // API 标题

ApiInfo apiInfo = builder.build();

docket.apiInfo(apiInfo); // 设置 API 信息



// 配置扫描范围，仅包含标注了 @ApiOperation 的方法

docket.select()

.apis(RequestHandlerSelectors.withMethodAnnotation(ApiOperation.class)) // 筛选有注解的方法

.paths(PathSelectors.any()) // 扫描所有路径

.build();



// 配置 JWT 支持

// 1. 配置需要提交的参数（如 token）

List apikey = new ArrayList<>();

apikey.add(new ApiKey("token", "token", "header")); // 添加 "token" 参数

docket.securitySchemes(apikey);



// 2. 配置全局令牌作用域

AuthorizationScope scope = new AuthorizationScope("global", "accessEverything"); // 全局访问权限

SecurityReference reference = new SecurityReference("token", new AuthorizationScope[]{scope});

SecurityContext context = SecurityContext.builder()

.securityReferences(List.of(reference)) // 配置令牌

.build();

docket.securityContexts(List.of(context)); // 设置安全上下文



return docket; // 返回 Docket 实例

}

}

---

三、配置的核心知识点

1. Swagger 基本配置

• 注解：

  • @Configuration：标记此类为 Spring 配置类。

  • @EnableSwagger2：启用 Swagger 生成文档功能。

• Docket 对象：

  • Swagger 的核心配置类，用于设置文档信息、API 扫描范围和安全认证等功能。

2. API 信息配置

通过 ApiInfoBuilder，可以配置文档的基本信息，例如标题、描述等。

ApiInfoBuilder builder = new ApiInfoBuilder();

builder.title("EMOS在线办公系统"); // 配置文档标题

ApiInfo apiInfo = builder.build();

docket.apiInfo(apiInfo); // 将信息设置到 Docket 对象中

3. API 扫描范围

使用 RequestHandlerSelectors 和 PathSelectors 定义需要生成文档的 API 范围：

• 扫描标注了 @ApiOperation 的方法：

selectorBuilder.apis(RequestHandlerSelectors.withMethodAnnotation(ApiOperation.class))

• 扫描所有路径：

java selectorBuilder.paths(PathSelectors.any());

4. JWT 支持

为了保护 API 的安全性，Swagger 提供了内置的认证支持。

• 配置需要的参数（如 token）：

apikey.add(new ApiKey("token", "token", "header")); // 定义请求头中的令牌
docket.securitySchemes(apikey);

• 定义全局作用域，让用户一次认证后对所有受保护的 API 生效：

AuthorizationScope scope = new AuthorizationScope("global", "accessEverything");
SecurityReference reference = new SecurityReference("token", new AuthorizationScope[]{scope});
SecurityContext context = SecurityContext.builder()
        .securityReferences(List.of(reference))
        .build();
docket.securityContexts(List.of(context));

四、实际使用 

示例代码：

package com.example.emos.wx.controller;

import com.example.emos.wx.common.util.R;
import io.swagger.annotations.Api;
import io.swagger.annotations.ApiOperation;
import org.springframework.web.bind.annotation.GetMapping;
import org.springframework.web.bind.annotation.RequestMapping;
import org.springframework.web.bind.annotation.RestController;

@RestController
@RequestMapping("/test")
@Api("测试Web接口")  //类使用的注解@Api
public class TestController {

    @GetMapping("/sayHello")
    @ApiOperation("最简单的测试方法")  //方法使用的注解@ApiOperation
    public R sayHello(){
        return R.ok().put("message","HelloWorld");
    }
}

五、效果展示

配置完成后，启动 Spring Boot 项目，访问 Swagger UI 页面，可以看到如下界面：

个人建议： 

        swagger配置方法不需要去刻意的记，我们只需要知道那些地方是做什么的就行，这样我们需要用到的时候可以直接修改模板，提高开发效率。