Set List of Objects in Swagger API Response – 设置Swagger API响应中的对象列表

最后修改: 2022年 3月 13日

1. Overview


In this tutorial, we’ll learn how to modify the Swagger API Response. First, we’ll start with some explanations of the OpenAPI Specification and Swagger API Response. Then, we’ll implement a simple example using Spring Boot to document a spring REST API using OpenApi 3.0. After that, we’ll use Swagger’s annotations to set the response body to deliver a list of objects.

在本教程中,我们将学习如何修改Swagger API的响应。首先,我们将从对OpenAPI规范和Swagger API响应的一些解释开始。然后,我们将使用Spring Boot实现一个简单的示例使用OpenApi 3.0记录一个spring REST API之后,我们将使用Swagger的注释来设置响应体,以交付一个对象列表。

2. Implementation


In this implementation, we’re going to set up a simple Spring Boot project with Swagger UI. Consequently, we’ll have the Swagger UI including all the endpoints of our application. After that, we will modify the response body to return a list.

在这个实现中,我们将建立一个带有Swagger UI的简单Spring Boot项目。因此,我们会有Swagger UI,包括我们应用程序的所有端点。之后,我们将修改响应体以返回一个列表。

2.1. Setting up a Spring Boot Project with Swagger UI

2.1.用Swagger UI设置Spring Boot项目

Firstly, we’ll create a ProductService class in which we save a list of products. Next, in ProductController, we define REST APIs to let the users get the list of created products.

首先,我们将创建一个ProductService类,在其中保存一个产品列表。接下来,在ProductController中,我们定义REST API,让用户获得创建的产品列表。

First, let’s define the Product class:


public class Product {
    String code;
    String name;

    // standard getters and setters

Then, we implement the ProductService class:


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

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

Finally, we’ll have a Controller class to define the REST APIs:

最后,我们将有一个Controller类来定义REST APIs。

public class ProductController {
    final ProductService productService;

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

    public List<Product> getProductsList(){
        return productService.getProductsList();

2.2. Modifying Swagger API Response

2.2.修改Swagger API响应

There are several Swagger annotations available to document the REST APIs. Using @ApiResponses, we can define an array of @ApiResponse to define our expected responses for a REST API.

有几个Swagger注解可用于记录REST APIs。使用@ApiResponses,我们可以定义一个@ApiResponse数组来定义我们对REST API的预期响应。

Now, let’s use @ApiResponses to set the response content to a list of Product objects for the getProductList method:


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

In this example, we set the media type to application/json in the response body. In addition, we modified the response body using the content keyword. Also, using the array keyword, we set the response to an array of Product objects:


List of Products


3. Conclusion


In this tutorial, we had a quick look at OpenAPI Specification and Swagger API Response. Swagger provides us with various annotations such as @ApiResponses, including different keywords. Therefore, we can easily use them to modify requests and responses to meet the requirements of our application. In our implementation, we used @ApiResponses to modify the content in the Swagger response body.

在本教程中,我们快速了解了OpenAPI规范和Swagger API响应。Swagger为我们提供了各种注释,如@ApiResponses,包括不同的关键字。因此,我们可以轻松地使用它们来修改请求和响应,以满足我们应用程序的要求。在我们的实现中,我们使用@ApiResponses来修改Swagger响应体中的内容。

As always, the code is available over on GitHub.