SpringBoot集成Swagger 2

在 Spring Boot 中，使用 Swagger 2 可以非常方便地構(gòu)建和測試 RESTful APIs。Swagger 提供了交互式的 API 文檔頁面，使開發(fā)者和用戶能夠直觀地了解和使用 API。

以下是如何在 Spring Boot 中集成 Swagger 2 的詳細(xì)步驟。

1. 添加 Maven 依賴

在項(xiàng)目的 pom.xml 中添加 Swagger 相關(guān)依賴：

<dependencies>
    <!-- Swagger 依賴 -->
    <dependency>
        <groupId>io.springfox</groupId>
        <artifactId>springfox-boot-starter</artifactId>
        <version>3.0.0</version> <!-- 確保版本兼容 -->
    </dependency>
</dependencies>

如果使用 Gradle，添加：

implementation 'io.springfox:springfox-boot-starter:3.0.0'

2. 配置 Swagger

創(chuàng)建一個(gè)配置類，用于初始化 Swagger 2：

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;
?
@Configuration
public class SwaggerConfig {
?
    @Bean
    public Docket api() {
        return new Docket(DocumentationType.SWAGGER_2)
                .select()
                // 掃描指定的包路徑
                .apis(RequestHandlerSelectors.basePackage("com.example.controller"))
                .paths(PathSelectors.any()) // 匹配所有路徑
                .build();
    }
}

3. 編寫 RESTful API

創(chuàng)建一個(gè)簡單的 Controller 測試 Swagger 的效果：

package com.example.controller;
?
import org.springframework.web.bind.annotation.*;
?
@RestController
@RequestMapping("/api/v1")
public class UserController {
?
    @GetMapping("/users")
    public String getUsers() {
        return "List of users";
    }
?
    @PostMapping("/users")
    public String createUser(@RequestBody String user) {
        return "User created: " + user;
    }
?
    @GetMapping("/users/{id}")
    public String getUserById(@PathVariable String id) {
        return "User with ID: " + id;
    }
?
    @DeleteMapping("/users/{id}")
    public String deleteUser(@PathVariable String id) {
        return "User deleted with ID: " + id;
    }
}

4. 訪問 Swagger UI

啟動 Spring Boot 應(yīng)用后，訪問以下 URL：

Swagger UI 頁面： http://localhost:8080/swagger-ui/

注意： 默認(rèn)情況下，Swagger UI 會根據(jù)配置類掃描并生成文檔頁面，展示所有 RESTful API 的詳細(xì)信息和接口調(diào)用示例。

5. 示例文檔頁面

Swagger 頁面會根據(jù) UserController 自動生成如下 API 文檔：

GET /api/v1/users
POST /api/v1/users
GET /api/v1/users/{id}
DELETE /api/v1/users/{id}

通過頁面可以直接發(fā)送請求并查看響應(yīng)。

6. 其他 Swagger 配置項(xiàng)

全局 API 信息

在 SwaggerConfig 中，可以設(shè)置全局的 API 信息，比如標(biāo)題、版本、描述等：

import springfox.documentation.service.ApiInfo;
import springfox.documentation.service.Contact;
import springfox.documentation.spi.DocumentationType;
import springfox.documentation.spring.web.plugins.Docket;
import springfox.documentation.builders.ApiInfoBuilder;
?
@Bean
public Docket api() {
    return new Docket(DocumentationType.SWAGGER_2)
            .select()
            .apis(RequestHandlerSelectors.any())
            .paths(PathSelectors.any())
            .build()
            .apiInfo(apiInfo());
}
?
private ApiInfo apiInfo() {
    return new ApiInfoBuilder()
            .title("My RESTful API")
            .description("This is a sample API documentation using Swagger2")
            .version("1.0")
            .contact(new Contact("Your Name", "https://example.com", "email@example.com"))
            .build();
}

隱藏或忽略某些 API

對于 Controller 或 API 方法，可以使用注解 @ApiIgnore 來隱藏不希望暴露的接口。

import springfox.documentation.annotations.ApiIgnore;
?
@ApiIgnore
@RestController
public class HiddenController {
    // 這個(gè)類不會在 Swagger 文檔中顯示
}

7. 整合 Spring Security（可選）

如果項(xiàng)目中啟用了 Spring Security，需要為 Swagger UI 相關(guān)資源路徑配置放行：

@Override
protected void configure(HttpSecurity http) throws Exception {
    http.authorizeRequests()
        .antMatchers("/swagger-ui/**", "/v2/api-docs", "/swagger-resources/**", "/webjars/**").permitAll()
        .anyRequest().authenticated();
}

總結(jié)

通過集成 Swagger 2，開發(fā)者可以直觀地管理和測試 RESTful APIs，主要步驟包括：

添加依賴。
配置 SwaggerConfig。
編寫 Controller。
訪問 Swagger UI 測試接口。

這種方式特別適合團(tuán)隊(duì)協(xié)作，便于前后端聯(lián)調(diào)和文檔維護(hù)。

posted @ 2024-11-29 17:46 luorx 閱讀(952) 評論(0) 收藏舉報(bào)

刷新頁面返回頂部

luorongxin