1. Обзор
Мы можем использовать Swagger UI в качестве платформы для удобной визуализации интерфейсов API и взаимодействия с ними. Это мощный инструмент для создания структур API с минимальной необходимой настройкой.
В этой статье мы сосредоточимся на использовании Swagger с API REST Spring Boot . В частности, мы рассмотрим различные способы скрытия поля запроса в пользовательском интерфейсе Swagger.
2. Введение
Для простоты мы создадим базовое приложение Spring Boot и изучим API с помощью пользовательского интерфейса Swagger.
Давайте создадим простое приложение ArticleApplication , используя Spring Boot. Мы предоставляем два API с помощью ArticlesController . Используя GET API, мы хотим получить подробную информацию обо всех статьях.
С другой стороны, мы используем POST API для добавления деталей для новой статьи:
@RestController
@RequestMapping("/articles")
public class ArticlesController {
@Autowired
private ArticleService articleService;
@GetMapping("")
public List<Article> getAllArticles() {
return articleService.getAllArticles();
}
@PostMapping("")
public void addArticle(@RequestBody Article article) {
articleService.addArticle(article);
}
}
Мы будем использовать класс Article в качестве объекта передачи данных (DTO) для этих API. Теперь добавим несколько полей в класс Article :
public class Article {
private int id;
private String title;
private int numOfWords;
// standard getters and setters
}
Мы можем получить доступ к пользовательскому интерфейсу Swagger по адресу http://localhost:8080/swagger-ui/#/articles-controller . Давайте запустим приложение и посмотрим на поведение по умолчанию для двух вышеуказанных API:
В POST API мы принимаем все данные, а именно id , title и numOfWords , от пользователя. В GET API мы возвращаем те же поля в ответе. Мы видим, что по умолчанию Swagger показывает все поля для обоих API.
Теперь предположим, что мы хотим использовать отдельную внутреннюю логику для установки поля id . В таком сценарии мы не хотим, чтобы пользователь вводил информацию, связанную с полем id . Чтобы избежать путаницы, мы хотим скрыть это поле в пользовательском интерфейсе Swagger.
Ближайший вариант, который приходит в голову, — это создание отдельного DTO и скрытие в нем нужных полей. Этот метод может быть полезен, если мы хотим добавить дополнительную логику для DTO. Мы можем использовать этот вариант, если он соответствует нашим общим требованиям.
В этой статье давайте используем различные аннотации, чтобы скрыть поля в пользовательском интерфейсе Swagger.
3. Использование @JsonIgnore
@JsonIgnore — это стандартная аннотация Джексона . Мы можем использовать его, чтобы указать, что поле должно игнорироваться Джексоном во время сериализации и десериализации . Мы можем добавить аннотацию только к полю, которое будет игнорироваться, и она скроет как геттеры, так и сеттеры для указанного поля.
Давайте попробуем:
@JsonIgnore
private int id;
Давайте перезапустим приложение и изучим пользовательский интерфейс Swagger:
Мы видим, что теперь поле id не отображается в описаниях API. Swagger также предоставляет аннотации для достижения аналогичного поведения.
4. Использование @ApiModelProperty
@ApiModelProperty предоставляет метаданные, относящиеся к свойствам объекта модели . Мы можем использовать скрытое свойство аннотации, чтобы скрыть поле в определении объекта модели в пользовательском интерфейсе Swagger.
Давайте попробуем это для поля id :
@ApiModelProperty(hidden = true)
private int id;
В приведенных выше сценариях мы обнаруживаем, что поле id скрыто как для GET , так и для POST API. Предположим, мы хотим разрешить пользователям просматривать сведения об идентификаторе как часть ответа GET API. В этом случае нужно искать другие варианты.
Swagger также предоставляет альтернативное свойство readOnly . Мы можем использовать его, чтобы скрыть указанное поле во время операций обновления, но по-прежнему отображать его для операций извлечения .
Давайте рассмотрим это:
@ApiModelProperty(readOnly = true)
private int id;
Теперь давайте проверим обновленный пользовательский интерфейс Swagger:
Мы видим, что поле id теперь видимо для GET API, но остается скрытым для POST API — оно поддерживает операции только для чтения .
Это свойство помечено как устаревшее, начиная с версии 1.5.19 . Для более высоких версий давайте рассмотрим другие аннотации.
5. Использование @JsonProperty
Джексон предоставляет аннотацию @JsonProperty . Мы можем использовать его для добавления `метаданных, связанных с геттерами/сеттерами поля POJO, которые можно использовать во время сериализации/десериализации объектов. Мы можем **установить свойство доступа аннотации, чтобы разрешить только операции чтения` ** в определенном поле:
@JsonProperty(access = JsonProperty.Access.READ_ONLY)
private int id;
Таким образом, мы можем скрыть поле id для определения модели POST API, но по-прежнему можем отображать его в ответе GET API.
Давайте рассмотрим другой способ достижения желаемой функциональности.
6. Использование @ApiParam
@ApiParam также является аннотацией Swagger, которую мы можем использовать для указания метаданных, связанных с параметрами запроса. Мы можем установить для скрытого свойства значение true , чтобы скрыть любое свойство. Однако здесь у нас есть ограничение: это работает, только если мы используем @ModelAttribute вместо @RequestBody для доступа к данным запроса.
Давайте попробуем:
@PostMapping("")
public void addArticle(@ModelAttribute Article article) {
articleService.addArticle(article);
}
@ApiParam(hidden = true)
private int id;
Давайте рассмотрим спецификации пользовательского интерфейса Swagger для этого случая:
Нам удалось скрыть поле id в определении данных запроса POST API.
7. Заключение
Мы рассмотрели различные варианты изменения видимости свойств объекта модели в пользовательском интерфейсе Swagger. Обсуждаемые аннотации также предлагают несколько других функций, которые мы можем использовать для обновления спецификаций Swagger. Мы должны использовать соответствующие методы в соответствии с нашими требованиями.
Исходный код доступен на GitHub .