Swagger 2 или 3 для Spring Data Rest

У меня есть приложение для весенней загрузки, использующее Spring Data Rest. У меня проблема с предоставлением хорошо читаемой документации по API с использованием чванства. Я пробовал spring fox и springdoc, но у каждого свои проблемы

  1. Весенняя лиса:
  • Не могу изменить название тега репозитория, только описание
  • Нет поддержки прогнозов
  • Пока нет поддержки openAPI3 (на самом деле это не большая проблема)
  1. Springdoc (https://springdoc.org/)
  • Не могу изменить ни имя тега, ни описание (@Tag не работает в репозиториях)
  • Нет поддержки прогнозов
  • Одно и то же репо получает 3 тега, например, books-entity-controller, books-search-controller (с методами родительского класса) и books-property-reference-controller (с ненужным перечислением URL-адресов /{id}/{property}).

Есть способ лучше? Мне нравится spring fox за то, что он не предоставляет более одного тега, а также автоматически сгенерированные имена тегов лучше, например, Books Entity вместо books-entity-controller. Но было бы лучше либо настроить его, либо найти лучшую альтернативу.

Источник

2 ответа

Springdoc

Не могу изменить ни имя тега, ни описание (@Tag не работает в репозиториях)

а также

Одно и то же репо получает 3 тега

Вы можете настроить это. Используйте следующее на уровне класса контроллера.

@Tag(name = "Name of the Tag", description = "Description of the tag")

или

@Tags(value = {
    // Multiple @Tag annotations separated by comma ,
})

или следующее на уровне метода.

@Operation(tags = {"Tag 1", "Tag 2"})

Помнить:

  • @Tag на уровне класса переопределит теги уровня операции для конкретного класса.
  • Тег уровня класса может иметь только 1 значение.

Поэтому, если вам нужен контроллер с несколькими тегами, вы должны изолировать его в другом классе, у которого нет @Tag на уровне класса.

Нет поддержки прогнозов

Я никогда не пользовался проекциями. Я обычно использую@JsonIgnore чтобы удалить ненужные, но это зависит от вашего варианта использования.

Если вы хотите скрыть что-то из схемы, используйте метод ниже

@Schema(description = "Example POJO to demonstrate the hidden attribute")
class Example {
    ...
    @Schema(hidden = true)    // <--- Will be hidden from the Swagger UI completely 
    String exampleId;
    ...
}

Надеюсь, это поможет. Оставьте комментарий для любых разъяснений.

Источник

Я рекомендую Spring REST Docs вместо Swagger. Spring REST Docs тестируется, чтобы гарантировать, что ваша документация по API всегда синхронизируется с вашим API. Выступление Энди объясняет, почему Spring REST Docs более подходит для документации API, чем Swagger.

Вы можете найти официальное простое руководство и другие образцы.

Мой проект Github использует его. Вы можете клонировать репозиторий и просмотреть сгенерированный HTML- код документации /sga-booking/index.html. Связанный файл Spring REST Docs:

Если вы найдете мой Github полезным, поставьте ему звезду.

Источник
Другие вопросы по тегам