«1. Обзор

При создании документации Swagger нам часто нужно скрыть конечные точки от доступа к конечным пользователям. Чаще всего это делается, когда конечная точка еще не готова. Кроме того, у нас могут быть некоторые частные конечные точки, которые мы не хотим раскрывать.

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

2. Скрытие конечной точки с помощью @ApiIgnore

Аннотация @ApiIgnore позволяет скрыть конечную точку. Давайте добавим эту аннотацию для конечной точки в наш контроллер: 

@ApiIgnore
@ApiOperation(value = "This method is used to get the author name.")
@GetMapping("/getAuthor")
public String getAuthor() {
    return "Umang Budhwar";
}

3. Скрытие конечной точки с помощью @ApiOperation

Кроме того, мы можем использовать @ApiOperation, чтобы скрыть одну конечную точку: 

@ApiOperation(value = "This method is used to get the current date.", hidden = true)
@GetMapping("/getDate")
public LocalDate getDate() {
    return LocalDate.now();
}

Обратите внимание, что мы необходимо установить для скрытого свойства значение true, чтобы Swagger игнорировал эту конечную точку.

4. Скрытие всех конечных точек с помощью @ApiIgnore

Тем не менее, иногда нам нужно скрыть все конечные точки класса контроллера. Мы можем добиться этого, аннотировав класс контроллера с помощью @ApiIgnore: 

@ApiIgnore
@RestController
public class RegularRestController {
    // regular code
}

Следует отметить, что это скроет сам контроллер из документации.

6. Скрытие конечной точки с помощью @Hidden

Если мы используем OpenAPI v3, мы можем скрыть конечную точку с помощью аннотации @Hidden: 

@Hidden
@GetMapping("/getAuthor")
public String getAuthor() {
    return "Umang Budhwar";
}

7. Скрытие всех конечных точек с помощью @Hidden

Точно так же мы можем пометить контроллер @Hidden, чтобы скрыть все конечные точки: 

@Hidden
@RestController
public class RegularRestController {
    // regular code
}

Это также скроет контроллер из документации.

Примечание. Мы можем использовать @Hidden только при использовании OpenAPI. Поддержка этой аннотации в Swagger v3 все еще продолжается.

8. Заключение

В этом руководстве мы увидели, как мы можем скрыть конечные точки из документации Swagger. Мы обсудили, как скрыть одну конечную точку, а также все конечные точки класса контроллера.

Как всегда, полный код примеров Swagger доступен на GitHub, а примеры OpenAPI v3 также доступны на GitHub.