Перейти к основному содержимому

Установить список объектов в ответе Swagger API

· 3 мин. чтения

1. Обзор​

В этом руководстве мы узнаем, как изменить ответ Swagger API. Во-первых, мы начнем с некоторых пояснений спецификации OpenAPI и ответа Swagger API. Затем мы реализуем простой пример с использованием Spring Boot для документирования Spring REST API с использованием OpenApi 3.0 . После этого мы будем использовать аннотации Swagger, чтобы настроить тело ответа для доставки списка объектов.

2. Реализация​

В этой реализации мы собираемся настроить простой проект Spring Boot с пользовательским интерфейсом Swagger. Следовательно, у нас будет пользовательский интерфейс Swagger, включающий все конечные точки нашего приложения. После этого мы изменим тело ответа, чтобы оно возвращало список.

2.1. Настройка проекта Spring Boot с пользовательским интерфейсом Swagger​

Во-первых, мы создадим класс ProductService , в котором мы сохраним список продуктов. Затем в ProductController мы определяем REST API, чтобы пользователи могли получать список созданных продуктов.

Во-первых, давайте определим класс Product : 

public class Product {
    String code;
    String name;

<span style="font-weight: 400">    // standard getters and setters</span>
}

Затем мы реализуем класс 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, чтобы установить содержимое ответа в список объектов 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();
}

В этом примере мы устанавливаем тип мультимедиа в application/json в теле ответа. Кроме того, мы изменили тело ответа, используя ключевое слово content . Кроме того, используя ключевое слово массива , мы устанавливаем ответ на массив объектов Product :

./1d81f3a8082b01f018e413c7b8eeb311.png

3. Заключение​

В этом руководстве мы кратко рассмотрели спецификацию OpenAPI и ответ Swagger API. Swagger предоставляет нам различные аннотации, такие как @ApiResponses , включая различные ключевые слова. Поэтому мы можем легко использовать их для изменения запросов и ответов в соответствии с требованиями нашего приложения. В нашей реализации мы использовали @ApiResponses для изменения содержимого в теле ответа Swagger.

Как всегда, код доступен на GitHub .