在Swagger API响应中设置对象列表

1. 概述

在这个教程中，我们将学习如何修改Swagger API响应。首先，我们来解释一下OpenAPI规范和Swagger API响应。然后，我们将使用Spring Boot实现一个简单的示例，来使用OpenApi 3.0为Spring REST API提供文档。接着，我们将使用Swagger的注解设置响应体，返回一个对象列表。

2. 实现

在这个实现中，我们将设置一个带有Swagger UI的简单Spring Boot项目。这样，我们就有了包含应用程序所有端点的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。通过使用@ApiResponses，我们可以定义一个ApiResponse数组，来指定REST API的预期响应。

现在，我们使用@ApiResponses为getProductList方法设置响应内容为一个Product对象的列表：

@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提供了各种注解，如@ApiResponses，包括不同的关键词，使我们能够轻松地根据应用需求修改请求和响应。在我们的示例中，我们使用了@ApiResponses来修改Swagger响应体的内容。

如往常一样，代码可在GitHub上找到。