Пример
Код описанного контроллера
Сгенерированная документация
<dependency>
<groupId>org.springdoc</groupId>
<artifactId>springdoc-openapi-ui</artifactId>
<version>1.7.0</version>
</dependency>
<dependency>
<groupId>org.springdoc</groupId>
<artifactId>springdoc-openapi-webmvc-core</artifactId>
<version>1.7.0</version>
</dependency>
<dependency>
<groupId>org.springdoc</groupId>
<artifactId>springdoc-openapi-starter-webmvc-ui</artifactId>
<version>2.1.0</version>
</dependency>
<dependency>
<groupId>org.springdoc</groupId>
<artifactId>springdoc-openapi-starter-webmvc-api</artifactId>
<version>2.1.0</version>
</dependency>
@Tag - описание контроллера
@Operation - описание метода контроллера
@Parameter - описание параметров метода
@ApiResponse - описание ответа метода контроллера
Если описывается несколько ответов, то их можно объединить группу
@ApiResponses(
@ApiResponse(...),
@ApiResponse(...),
@ApiResponse(...)
)
@Content - описание контента
(можно использовать значения из org.springframework.http.MediaType)
@ExampleObject - описание примеров
используется в examples = {...}
И класс и поля описываем одной аннотацией
@Schema
Если не хотим передавать поля
@Schema(accessMode = Schema.AccessMode.READ_ONLY)
@ArraySchema() - данных которые передаются как массив
В принципе можно указывать валидацию (я еще нигде пока не использовал)
@Min(1)
@Max(999)
private Integer id;
или
@NotBlan
@Size(min = 1, max = 100)
private String name;
@Hidden - исключить контроллер
@Operation(hidden = true) - исключить метод
Очень часто описание хочется видеть в виде списка или в несколько строк, т.е. с переносом строки.
Подстановка известных мне символов переноса строки результата не дал, но поиск в гугле был более результативен.
Можно использовать в тексе описания \n\n (именно два)
description = "Работа с базовыми функциями\n\n- Первая базовая функция\n\n- Вторая базовая функция"
или
Использовать текстовый блок с разделяющей строкой (использование пустых строк)
description = """
Работа с базовыми функциями:
- Первая базовая функция
- Вторая базовая функция
""")
Результат обоих вариантов будет такое описание:
Работа с базовыми функциями:
- Первая базовая функция
- Вторая базовая функция
Код описанного контроллера
Сгенерированная документация