1. Overview

1.概述

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

2.实施

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:

首先，我们来定义Product类。

public class Product {
    String code;
    String name;

    // standard getters and setters
}

Then, we implement the ProductService class:

然后，我们实现ProductService类。

@Service
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。

@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. 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:

现在，让我们使用@ApiResponses将响应内容设置为Product对象的列表，用于getProductList方法。

@ApiResponses(
  value = {
    @ApiResponse(
      content = {
        @Content(
          mediaType = "application/json",
          array = @ArraySchema(schema = @Schema(implementation = Product.class)))
      })
  })
@GetMapping("/products")
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:

在这个例子中，我们在响应体中把媒体类型设置为application/json。此外，我们使用content关键字修改了响应体。另外，使用array关键字，我们将响应设置为一个Product对象的数组。

3. Conclusion

3.总结

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.

像往常一样，代码可在GitHub上获得。