知識庫 / REST RSS 訂閱

1. 概述

本教程將介紹如何修改 Swagger API 響應。首先，我們將對 OpenAPI 規範和 Swagger API 響應進行一些解釋。然後，我們將使用 Spring Boot 來實現一個簡單的示例，利用 OpenAPI 3.0 文檔一個 Spring REST API。 之後，我們將使用 Swagger 的註解來設置響應體，從而提供一個包含對象的列表。

2. 實現

在本次實現中，我們將創建一個簡單的 Spring Boot 項目，並配置 Swagger UI。 這樣，Swagger UI 將包含我們應用程序的所有端點。 隨後，我們將修改響應體以返回一個列表。

2.1. 使用 Swagger UI 設置 Spring Boot 項目

首先，我們將創建一個 ProductService 類，其中保存一個產品列表。 接下來，在 ProductController 中，我們定義 REST API 以允許用户獲取創建的產品列表。

首先，讓我們定義 Product 類：

public class Product {
    String code;
    String name;

    // standard getters and setters
}

然後，我們實現 ProductService 類：

@Service
public class ProductService {
    List<Product> productsList = new ArrayList<>();

    public List<Product> getProductsList() {
        return productsList;
    }
}

最後，我們將有一個 Controller 類來定義 REST API：

@RestController
public class ProductController {
    final ProductService productService;

    public ProductController(ProductService productService) {
        this.productService = productService;
    }

    @GetMapping("/products")
    public List<Product> getProductsList(){
        return productService.getProductsList();
    }
}

2.2. 修改 Swagger API 響應

有多種 Swagger 註解可用於文檔化 REST API。通過使用 <em/>@ApiResponses</em/>，我們可以定義一個包含 @ApiResponse 對象的數組，從而定義 REST API 的預期響應。

現在，我們使用 @ApiResponses 來將 getProductList 方法的響應內容設置為一個 `Product</em/> 對象列表：

@ApiResponses(
  value = {
    @ApiResponse(
      content = {
        @Content(
          mediaType = "application/json",
          array = @ArraySchema(schema = @Schema(implementation = Product.class)))
      })
  })
@GetMapping("/products")
public List<Product> getProductsList() {
    return productService.getProductsList();
}

在此示例中，我們設置了響應體中的媒體類型為 application/json。 此外，我們使用 content 關鍵字修改了響應體。 另外，使用 array 關鍵字，我們將響應設置為 Product 對象數組：

 

3. 結論

在本教程中，我們快速瞭解了 OpenAPI 規範和 Swagger API 響應。Swagger 提供了諸如 <em @ApiResponses</em> 這樣多種註解，包括不同的關鍵詞。因此，我們可以輕鬆地利用它們來修改請求和響應，以滿足我們應用程序的要求。在我們的實現中，我們使用 <em @ApiResponses</em> 來修改 Swagger 響應體中的內容。