在 Spring Boot 中使用 Swagger

介紹

在開發(fā) Web 應用時，API 文檔的編寫和維護是一項非常重要的工作。Swagger 是一款非常流行的 API 文檔工具，可以自動生成 API 文檔，并提供一系列的交互式工具，如測試界面、調試界面等，方便開發(fā)者進行 API 的調試和測試。本文將介紹如何在 Spring Boot 應用中使用 Swagger。

引入依賴

首先需要在 pom.xml 文件中引入 Swagger 的依賴：

<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>

上述依賴中，springfox-swagger2 是 Swagger 的核心庫，提供了 API 文檔的生成和管理功能；springfox-swagger-ui 則提供了 Swagger 的用戶界面，包括交互式測試工具、調試工具等。

配置 Swagger

接下來需要在 Spring Boot 應用中配置 Swagger?？梢酝ㄟ^添加一個 SwaggerConfig 類來配置 Swagger。以下是一個簡單的 SwaggerConfig 配置示例：

@Configuration
@EnableSwagger2
public class SwaggerConfig {
 
    @Bean
    public Docket api() {
        return new Docket(DocumentationType.SWAGGER_2)
                .select()
                .apis(RequestHandlerSelectors.basePackage("com.example.demo"))
                .paths(PathSelectors.any())
                .build()
                .apiInfo(apiInfo());
    }
 
    private ApiInfo apiInfo() {
        return new ApiInfoBuilder()
                .title("API 文檔")
                .description("這是一個 Swagger API 文檔示例")
                .version("1.0.0")
                .build();
    }
 
}

上述配置中，@EnableSwagger2 注解表示啟用 Swagger 功能。Docket 類表示一個 API 文檔配置，可以設置 API 文檔的基本信息和請求接口的過濾條件。在上述示例中，設置了 API 文檔的基本信息和請求接口的過濾條件，包括 API 文檔的標題、描述、版本號等信息，以及過濾掉不需要生成 API 文檔的請求接口。

使用 Swagger

在 Spring Boot 應用中使用 Swagger 非常簡單，只需要在需要生成 API 文檔的方法上添加相應的注解即可。以下是常用的 Swagger 注解：

• @Api：表示一個 API 接口的基本信息，包括標題、描述、版本號等信息。
• @ApiOperation：表示一個 API 接口的詳細信息，包括請求方法、請求路徑、請求參數(shù)、請求體、響應信息等。
• @ApiParam：表示一個 API 接口的請求參數(shù)信息。
• @ApiModel：表示一個 API 接口的請求或響應模型信息。
• @ApiModelProperty：表示一個 API 接口的請求或響應模型屬性信息。

以下是一個示例代碼，演示如何在 Spring Boot 應用中使用 Swagger：

@RestController
@Api(tags = "用戶管理")
public class UserController {
 
    @Autowired
    private UserService userService;
 
    @ApiOperation(value = "獲取用戶信息", notes = "根據(jù)用戶 ID 獲取用戶信息")
    @ApiImplicitParam(name = "id", value = "用戶 ID", dataType = "Long", required = true)
    @GetMapping("/user/{id}")
    public User getUserById(@PathVariable Long id) {
        return userService.getUserById(id);
    }
 
    @ApiOperation(value = "創(chuàng)建用戶", notes = "創(chuàng)建一個新的用戶")
    @ApiImplicitParams({
            @ApiImplicitParam(name = "username", value = "用戶名", dataType = "String", required = true),
            @ApiImplicitParam(name = "password", value = "密碼", dataType = "String", required = true)
    })
    @PostMapping("/user")
    public User createUser(@RequestParam String username, @RequestParam String password) {
        return userService.createUser(username, password);
    }
 
}

在上述示例中，使用 @Api 注解標記了 UserController類，并指定了一個標簽 “用戶管理”。在 getUserById 方法和 createUser 方法中，分別使用了 @ApiOperation 注解標記了方法的詳細信息，包括請求方法、請求路徑、請求參數(shù)、請求體、響應信息等。同時使用了 @ApiImplicitParam 注解標記了請求參數(shù)的信息，包括參數(shù)名、參數(shù)類型、是否必須等。這些注解可以幫助 Swagger 自動生成 API 文檔，并提供交互式測試工具。

使用 Swagger UI

在應用啟動后，可以通過訪問 http://localhost:8080/swagger-ui.html 地址來打開 Swagger UI 界面。在 Swagger UI 界面中，可以看到生成的 API 文檔，并提供了一系列的交互式工具，如測試界面、調試界面等，方便開發(fā)者進行 API 的調試和測試。

結語

本文介紹了如何在 Spring Boot 應用中使用 Swagger，包括引入依賴、配置 Swagger、使用 Swagger 注解和使用 Swagger UI 界面。Swagger 可以幫助開發(fā)者快速生成 API 文檔，并提供一系列的交互式工具，方便開發(fā)者進行 API 的調試和測試。文章來源地址http://www.zghlxwxcb.cn/news/detail-502381.html

到了這里，關于Spring Boot 中如何使用 Swagger的文章就介紹完了。如果您還想了解更多內容，請在右上角搜索TOY模板網以前的文章或繼續(xù)瀏覽下面的相關文章，希望大家以后多多支持TOY模板網！