Swagger Basic Authentication（身份验证）配置

Swagger Basic Authentication（身份验证）是一种用于保护 API 接口的基本身份验证方法。它通过在每个请求中包含基本认证头部，即包含 Base64 编码的用户名和密码，来验证用户的身份。这种身份验证方法通常适用于需要对 API 进行访问控制的情况。

Basic Auth 使用场景

Swagger Basic Authentication 适用于需要对 API 进行访问控制的项目，特别是在以下情况下使用它是有意义的：

项目中有敏感数据或功能需要保护，只允许经过身份验证的用户访问。
需要将 API 暴露给第三方开发者，并希望对他们进行身份验证，以确保只有授权的开发者能够访问 API。

Basic Auth 用法介绍

使用 Swagger Basic Authentication（身份验证）功能需要配置相关的注解和设置。在 Swagger 注解中，可以使用@ApiOperation 的 authorizations 属性来配置所需的身份验证。示例代码如下：

@ApiOperation(value = "Get user by ID", authorizations = {
    @Authorization(value = "basicAuth")
})
@GetMapping("/{id}")
public User getUserById(@PathVariable("id") String id) {
    // ...
}

这里的authorizations属性指定了需要使用的身份验证方式为basicAuth。

实践案例

在 Swagger Editor 在线编辑器中，可以通过以下方式配置 Swagger Basic Authentication（身份验证）。首先，在 Swagger 配置文件中添加以下代码：

securityDefinitions:
  basicAuth:
    type: basic

然后，在需要进行身份验证的 API 接口上添加如下注解：

@ApiOperation(value = "Get user by ID", authorizations = {
    @Authorization(value = "basicAuth")
})
@GetMapping("/{id}")
public User getUserById(@PathVariable("id") String id) {
    // ...
}

这样配置后，Swagger UI 将显示一个用于输入用户名和密码的认证框。

在 SpringBoot 项目中配置

要在 SpringBoot 项目中配置 Swagger Basic Authentication（身份验证）功能注解，需要添加相应的依赖和配置。

在 Spring Boot 中配置 Swagger Basic Auth 需要进行以下步骤：

在 Maven 或 Gradle 的构建文件中，添加 Swagger 依赖。例如，使用 Maven，可以在pom.xml文件中添加以下依赖：

<dependency>
    <groupId>io.springfox</groupId>
    <artifactId>springfox-swagger2</artifactId>
    <version>2.9.2</version>
</dependency>
<dependency>
    <groupId>io.springfox</groupId>
    <artifactId>springfox-swagger-ui</artifactId>
    <version>2.9.2</version>
</dependency>

2. 创建一个配置类（例如，SwaggerConfig.java），用于配置 Swagger 并启用 Basic Auth：

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;
import springfox.documentation.swagger2.annotations.EnableSwagger2;

@Configuration
@EnableSwagger2
public class SwaggerConfig {

    @Bean
    public Docket api() {
        return new Docket(DocumentationType.SWAGGER_2)
                .select()
                .apis(RequestHandlerSelectors.any())
                .paths(PathSelectors.any())
                .build()
                .securitySchemes(Collections.singletonList(basicAuthScheme()));
    }

    private SecurityScheme basicAuthScheme() {
        return new BasicAuth("basicAuth");
    }

}

3. 配置 Basic Auth 的用户名和密码。在application.properties或application.yml文件中添加以下配置：

使用application.properties文件：

spring.security.user.name=admin
spring.security.user.password=password

使用application.yml文件：

spring:
  security:
    user:
      name: admin
      password: password

4. 启动 Spring Boot 应用程序后，可以通过访问http://localhost:8080/swagger-ui.html来查看 Swagger UI 界面。在输入框中输入配置的用户名和密码，即可进行 Basic Auth 身份验证。

注意：使用基本身份验证时，建议通过 HTTPS 进行通信以确保安全性。

注意事项

在使用 Swagger Basic Authentication（身份验证）时，需要注意以下事项：

需要正确配置用户名和密码，确保能够成功进行身份验证。
前端调用 API 时，需要在请求头中正确设置 Basic 认证头部。

Swagger 和 Apifox 整合

Swagger 管理接口有时很不方便，缺乏一定的安全性和团队间的分享协作，所以我更推荐使用 Apifox 的 IDEA 插件。你可以在 IDEA 中自动同步 Swagger 注解到 Apifox，一键生成接口文档，多端同步，非常方便测试和维护，这样就可以迅速分享 API 给其他小伙伴。

立即体验 Apifox

Apifox 是一个比 Postman 更强大的接口测试工具，Apifox = Postman + Swagger + Mock + JMeter，Apifox 支持调试 http（s）、WebSocket、Socket、gRPC、Dubbo 等协议的接口，并且集成了 IDEA 插件。

Apifox 的 IDEA 插件可以自动解析代码注释，并基于 Javadoc、KDoc 和 ScalaDoc 生成 API 文档。通过 IntelliJ IDEA 的 Apifox Helper 插件，开发人员可以在不切换工具的情况下将他们的文档与 Apifox 项目同步。

当在 IDEA 项目中有接口信息变动，只需右键点击「 Upload to Apifox」一键即可完成同步，无需奔走相告。团队成员可在 Apifox 中看到同步后的最新内容。

现在出发去 JetBrains 插件市场下载试试吧！或直接在 IDEA 内「plugin」入口直接搜索 Apifox Helper。

知识扩展：

参考链接：

Swagger 官方文档： https://swagger.io/docs/
SpringFox GitHub 仓库： https://github.com/springfox/springfox