淺析如何使用Swagger生成帶權(quán)限控制的API文檔

更新時(shí)間：2025年02月14日 11:23:09 作者：五行星辰

當(dāng)涉及到權(quán)限控制時(shí),如何生成既安全又詳細(xì)的?API?文檔就成了一個(gè)關(guān)鍵問(wèn)題,所以這篇文章小編就來(lái)和大家好好聊聊如何用?Swagger?來(lái)生成帶有權(quán)限控制的?API?文檔吧

在咱們的開(kāi)發(fā)工作里，API 文檔就像是項(xiàng)目的說(shuō)明書(shū)，清晰準(zhǔn)確的文檔能讓我們的開(kāi)發(fā)效率大幅提升。而當(dāng)涉及到權(quán)限控制時(shí)，如何生成既安全又詳細(xì)的 API 文檔就成了一個(gè)關(guān)鍵問(wèn)題。今天，我就和大家好好嘮嘮如何用 Swagger 來(lái)生成帶有權(quán)限控制的 API 文檔。

準(zhǔn)備工作

咱們做開(kāi)發(fā)，就像行軍打仗，工具和資源就是我們的“糧草”。在使用 Swagger 生成帶權(quán)限控制的 API 文檔之前，得先把相關(guān)的依賴(lài)添加到項(xiàng)目里。如果你用的是 Maven 項(xiàng)目，在 pom.xml 里加上下面這些依賴(lài)：

<dependencies>
    <!-- Swagger API 注解 -->
    <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>
    <!-- Spring Security -->
    <dependency>
        <groupId>org.springframework.boot</groupId>
        <artifactId>spring-boot-starter-security</artifactId>
    </dependency>
</dependencies>

這些依賴(lài)就像是我們的武器裝備，有了它們，我們才能在開(kāi)發(fā)的戰(zhàn)場(chǎng)上“披荊斬棘”。

配置 Swagger

有了依賴(lài)，接下來(lái)就要對(duì) Swagger 進(jìn)行配置，讓它能按照我們的需求生成 API 文檔。創(chuàng)建一個(gè) Swagger 配置類(lèi)，就像給一場(chǎng)演出搭建舞臺(tái)一樣：

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.basePackage("com.example.controller"))
               .paths(PathSelectors.any())
               .build();
    }
}

這里我們指定了要掃描的控制器包路徑，這樣 Swagger 就能知道從哪里獲取 API 的信息了。

權(quán)限控制

在實(shí)際的項(xiàng)目中，API 文檔往往包含了很多敏感信息，所以給文檔加上權(quán)限控制是非常必要的。我們用 Spring Security 來(lái)實(shí)現(xiàn)這個(gè)功能，創(chuàng)建一個(gè) Spring Security 配置類(lèi)：

import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import org.springframework.security.config.annotation.web.builders.HttpSecurity;
import org.springframework.security.config.annotation.web.configuration.EnableWebSecurity;
import org.springframework.security.core.userdetails.User;
import org.springframework.security.core.userdetails.UserDetails;
import org.springframework.security.core.userdetails.UserDetailsService;
import org.springframework.security.provisioning.InMemoryUserDetailsManager;
import org.springframework.security.web.SecurityFilterChain;
 
@Configuration
@EnableWebSecurity
public class SecurityConfig {
 
    @Bean
    public SecurityFilterChain securityFilterChain(HttpSecurity http) throws Exception {
        http
               .authorizeRequests()
               .antMatchers("/swagger-ui.html", "/swagger-resources/**", "/v2/api-docs").hasRole("ADMIN")
               .anyRequest().authenticated()
               .and()
               .httpBasic();
        return http.build();
    }
 
    @Bean
    public UserDetailsService userDetailsService() {
        UserDetails user =
             User.withDefaultPasswordEncoder()
               .username("admin")
               .password("password")
               .roles("ADMIN")
               .build();
 
        return new InMemoryUserDetailsManager(user);
    }
}

在這個(gè)配置里，我們規(guī)定只有擁有 ADMIN 角色的用戶(hù)才能訪問(wèn) Swagger UI 和 API 文檔相關(guān)的路徑，就像給文檔加上了一把安全鎖，只有有鑰匙的人才能打開(kāi)。

給 API 加上權(quán)限注解

在控制器的方法上，我們要添加權(quán)限注解和 Swagger 注解，這樣在生成的文檔里就能清楚地看到每個(gè) API 的權(quán)限要求了：

import io.swagger.annotations.Api;
import io.swagger.annotations.ApiOperation;
import org.springframework.security.access.prepost.PreAuthorize;
import org.springframework.web.bind.annotation.GetMapping;
import org.springframework.web.bind.annotation.RequestMapping;
import org.springframework.web.bind.annotation.RestController;
 
@RestController
@RequestMapping("/api")
@Api(value = "示例 API", description = "這是一個(gè)帶有權(quán)限控制的示例 API 文檔")
public class ExampleController {
 
    @GetMapping("/hello")
    @ApiOperation(value = "獲取問(wèn)候語(yǔ)", notes = "需要 ADMIN 角色才能訪問(wèn)")
    @PreAuthorize("hasRole('ADMIN')")
    public String hello() {
        return "Hello, World!";
    }
}

這里用 @PreAuthorize 注解對(duì)方法進(jìn)行權(quán)限控制，同時(shí)在 @ApiOperation 注解的 notes 屬性中說(shuō)明權(quán)限要求，就像給每個(gè) API 貼上了一個(gè)“使用說(shuō)明”。

查看文檔

當(dāng)我們完成了以上所有步驟，就可以啟動(dòng) Spring Boot 應(yīng)用程序，然后訪問(wèn) http://localhost:8080/swagger-ui.html（端口號(hào)根據(jù)實(shí)際情況修改）。這時(shí)瀏覽器會(huì)彈出 HTTP Basic 認(rèn)證對(duì)話(huà)框，輸入我們?cè)?SecurityConfig 中配置的用戶(hù)名和密碼（這里是 admin 和 password），認(rèn)證通過(guò)后就能看到帶有權(quán)限信息的 API 文檔了，就像打開(kāi)了一扇通往知識(shí)寶庫(kù)的大門(mén)。

注意事項(xiàng)

在實(shí)際項(xiàng)目中，我們要注意一些細(xì)節(jié)。比如，示例中使用的 withDefaultPasswordEncoder() 并不是很安全，建議使用 BCryptPasswordEncoder 等更安全的密碼存儲(chǔ)方式。另外，我們可以根據(jù)實(shí)際業(yè)務(wù)需求調(diào)整權(quán)限規(guī)則和認(rèn)證方式，像使用 OAuth2 等。

到此這篇關(guān)于淺析如何使用Swagger生成帶權(quán)限控制的API文檔的文章就介紹到這了,更多相關(guān)Swagger生成API文檔內(nèi)容請(qǐng)搜索腳本之家以前的文章或繼續(xù)瀏覽下面的相關(guān)文章希望大家以后多多支持腳本之家！

您可能感興趣的文章: