Java API 開發中使用 Swagger 的詳細介紹-java教程-PHP中文網

Java API 開發中使用 Swagger 的詳細介紹

WBOY

發布： 2023-06-17 23:38:37

原創

1393 人瀏覽過

在Java API開發中，Swagger是一個非常有用的工具。 Swagger是一個開源的API框架，用於描述、設計和產生RESTful風格的web服務。它提供了一組註解來幫助開發者描述API和參數。在本文中，我將詳細介紹如何在Java API開發中使用Swagger。

安裝Swagger

Swagger可以使用Maven來整合到Java專案中。您可以使用以下Maven依賴項新增Swagger到您的專案中：

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

登入後複製

配置Swagger

在您的Java應用程式中，您需要設定Swagger。為此，您可以建立一個設定類別來初始化Swagger：

@Configuration
@EnableSwagger2
public class SwaggerConfig {    
    @Bean
    public Docket api() { 
        return new Docket(DocumentationType.SWAGGER_2)  
          .select()                                  
          .apis(RequestHandlerSelectors.any())              
          .paths(PathSelectors.any())                          
          .build();                                          
    }
}

登入後複製

在上面的程式碼中，我們定義了一個Docket bean，是Swagger的主要介面。我們使用它來指定Swagger API的類型，並將其與應用程式的URL對應。

新增Swagger註解

現在，您可以在Java API中加入Swagger註解。以下是一些常用的Swagger註解和它們的用途：

@Api：用來描述整個API。
@ApiOperation：用來描述API操作。
@ApiParam：用來描述操作參數。
@ApiModel：用來提供API的模型屬性。
@ApiModelProperty：用來描述API模型的屬性。

這些註解可以放置在類別、方法、欄位和方法參數上，並且可以透過使用value和notes屬性提供有關API評論的資訊。

例如，如果您有以下程式碼片段：

@RestController
@RequestMapping("/users")
public class UserController {
    @GetMapping("/{id}")
    public User getUser(@PathVariable Long id) {
        // code to get user
    }
}

登入後複製

您可以使用Swagger註解來描述getUser方法：

@RestController
@RequestMapping("/users")
@Api(value="用户管理", tags="用户管理")
public class UserController {
 
    @GetMapping("/{id}")
    @ApiOperation(value="获取用户信息", notes="根据用户ID获取用户信息")
    @ApiImplicitParam(name = "id", value = "用户ID", required = true, dataType = "Long")
    public User getUser(@PathVariable Long id) {
        // code to get user
    }
}

登入後複製

在上面的程式碼中，我們使用了@Api和@ApiOperation註釋。 @Api註釋用於描述整個API，包括名稱和標籤。 @ApiOperation註釋用於描述操作的名稱，以及一些操作的筆記。

產生Swagger UI

現在，您的Java應用程式已經配置了Swagger和Swagger註釋，您可以使用Swagger UI來顯示和測試API。

為此，您可以將以下行新增至SwaggerConfig類別中的@Bean註解下：

@Configuration
@EnableSwagger2
public class SwaggerConfig {    
    @Bean
    public Docket api() { 
        return new Docket(DocumentationType.SWAGGER_2)  
          .select()                                  
          .apis(RequestHandlerSelectors.any())              
          .paths(PathSelectors.any())                          
          .build();                                          
    }

    @Bean
    public UiConfiguration uiConfig() {
        return UiConfigurationBuilder.builder()
            .docExpansion(DocExpansion.LIST)
            .build();
    }
}

登入後複製

這將新增一個uiConfig() bean，用於配置Swagger UI。使用上面的程式碼，我們將DocExpansion設定為LIST，以便在UI中預設展開所有操作。