返回

SpringDoc轻松配置与OAuth2完美集成，轻松驾驭API文档

后端

SpringDoc与OAuth2集成：增强你的API文档安全

背景

SpringDoc是一款强大的工具，用于生成美观且信息丰富的API文档。OAuth2是一种流行的身份认证协议，为API提供安全可靠的登录机制。本教程将指导你如何将OAuth2与SpringDoc集成，为你的swagger-ui页面添加登录认证功能。

SpringDoc基础配置

  1. 添加依赖： 在pom.xml文件中添加SpringDoc依赖项。

  2. 启用SpringDoc： 在SpringBoot启动类上添加@EnableOpenApi注解。

  3. 配置元数据： 在application.yml文件中配置OpenAPI元数据。

  4. 扫描API接口： SpringDoc会自动扫描带有@RestController注解的类，或通过配置springdoc.pathsToMatch进行手动指定。

集成OAuth2

  1. 添加OAuth2依赖： 在pom.xml文件中添加OAuth2依赖项。

  2. 配置认证： 在SpringBoot启动类上添加@EnableWebSecurity注解，并在configure方法中配置OAuth2认证。

  3. 配置AccessToken转换器： 创建一个AccessToken转换器，用于在swagger-ui页面上显示OAuth2登录按钮。

  4. 配置OAuth2授权服务器： 创建一个OAuth2授权服务器，用于获取访问令牌。

使用SpringDoc集成OAuth2

  1. 添加SpringDoc-OAuth2依赖： 在pom.xml文件中添加SpringDoc-OAuth2依赖项。

  2. 启用SpringDoc-OAuth2： 在SpringBoot启动类上添加@EnableOAuth2Security注解。

  3. 配置登录按钮： 在swagger-ui.html页面中添加OAuth2登录按钮。

  4. 配置JavaScript代码： 在JavaScript代码中添加OAuth2登录逻辑。

示例代码

// 配置OAuth2认证
@EnableWebSecurity
public class SecurityConfig extends WebSecurityConfigurerAdapter {

    @Override
    protected void configure(HttpSecurity http) throws Exception {
        http
                .csrf().disable()
                .authorizeRequests()
                .antMatchers("/swagger-ui.html", "/webjars/**").permitAll()
                .anyRequest().authenticated()
                .and()
                .oauth2Login();
    }
}

// 配置AccessToken转换器
@Bean
public OAuth2AccessTokenResponseClient<OAuth2AuthorizationCodeGrantRequest> accessTokenResponseClient() {
    DefaultOAuth2AccessTokenResponseClient<OAuth2AuthorizationCodeGrantRequest> accessTokenResponseClient = new DefaultOAuth2AccessTokenResponseClient<>();
    accessTokenResponseClient.setRequestEntityConverter(new OAuth2AccessTokenRequestEntityConverter());
    return accessTokenResponseClient;
}

// 配置OAuth2授权服务器
@Bean
public OAuth2AuthorizedClientService oauth2AuthorizedClientService() {
    OAuth2AuthorizedClientServiceBuilder builder = OAuth2AuthorizedClientServiceBuilder.build();
    builder.clientCredentials(clientRegistrationRepository);
    builder.authorizedClientRepository(authorizedClientRepository());
    builder.refreshTokenProvider(new RefreshTokenProvider());
    return builder.build();
}

// 配置登录按钮
<div id="swagger-ui">
    <div id="oauth2-container">
        <button id="oauth2-login-button" type="button">Login with OAuth2</button>
    </div>
</div>

// 配置JavaScript代码
$(document).ready(function() {
    $("#oauth2-login-button").click(function() {
        window.location.href = "/oauth2/authorization/google";
    });
});

总结

通过将SpringDoc与OAuth2集成，我们增强了API文档的安全性和可用性。现在，我们可以轻松地使用OAuth2登录swagger-ui页面，并获取访问令牌。这使得与API交互更加安全和便捷。

常见问题解答

  1. 如何添加其他OAuth2提供者？

    • 参照OAuth2提供者的文档添加必要的依赖项和配置。

  2. 如何自定义登录按钮的外观？

    • 在oauth2-container div中添加CSS样式。

  3. 如何禁用OAuth2认证？

    • 注释掉@EnableWebSecurity注解或从configure方法中删除OAuth2配置。

  4. 如何获取访问令牌？

    • 通过oauth2AuthorizedClientService.loadAuthorizedClient方法加载授权的客户端并检索访问令牌。

  5. 如何处理认证错误？

    • 在configure方法中添加exceptionHandling配置以处理认证错误。