Что было раньше: код или документация? OpenApi (OAS 3.0) и проблемы кодогенерации на Java

[boiarshinov]

Странно, что не упомянули аналог springdoc-openapi-ui — springfox, т.к. у Springfox в 5 раз больше звездочек на гитхабе (тут следует заметить, что ни тот, ни другой проект не имеют отношения к фреймворку Spring и не мейнтейнятся Pivotal'ом).
Мы у себя в проекте пользуемся springdoc-openapi-ui, потому что так исторически сложилось.
Для того чтобы не перегружать контроллер описаниями мы сначала придумали собственные аннотации, описывающие стандартные виды ответа сервера: @BadRequestApiResponse, @UnauthorizedApiResponse. Эти аннотации включали в себя обычные аннотации из io.swagger. Вот пример такой аннотации:

@Target(ElementType.METHOD)
@Retention(RetentionPolicy.RUNTIME)
@ApiResponse(
    responseCode = "400",
    description = "Incorrect input data",
    content = @Content(
        mediaType = MediaType.APPLICATION_JSON_VALUE,
        schema = @Schema(implementation = ErrorInfoResponse.class)
    )
)
public @interface BadRequestApiResponse {
}

В итоге в контроллере нужно было подробно описывать только положительный исход работы API, но и для этого мы потом тоже придумали аннотацию. Вот так стала выглядеть шапка метода контроллера (все названия и описания моделей изменены):

@GetMapping("/entities")
@SecureOperation(summary = "Поиск сущностей по фильтрам")
@OkApiResponse(description = "Отпагинированный список сущностей")
@BadRequestApiResponse
@UnauthorizedApiResponse
@InternalServerErrorApiResponse
SearchPage<EntityJsonPojo> findEntities(

Когда описание API стало занимать больше половины класса контроллера мы вынесли его в интерфейс.

Насчет того что модели становятся перегруженными, на мой взгляд, в этом нет ничего страшного — у них работа такая. В итоге на полями моделей висит три вида аннотаций: от com.fasterxml.jackson, от javax.validation и от io.swagger:

@Schema(description = "Мобильный телефон", example = "8005553535")
@NotNull
@JsonProperty(value = "phone")
@Pattern(regexp = "\\d{10}", message = "Телефон должен состоять из 10 символов (без 8)")
private String phoneNumber;

[Haspel]

Да, я тоже знаком со springfox и раньше очень активно использовал его в проектах из-за простоты интеграции, но когда мы начинали наш проект, решили переходить на OAS 3.0, а в актуальной версии springfox была доступна только 2-я версия спецификации. Последние версии springdoc уже поддерживали 3-ю версию спецификации и интегрировались также просто как springfox. Именно поэтому я выбирал его и сфокусировал основное внимание на этом инструменте.

[shuron]

"Обратный" подход тоесть contract first становится предпочтительней и важне как только вы подымаете голову из одного конкретного сервиса и смотрите на ваш сервисный ландшафт. Например если вы архитектор или проэктный мэнеджер или решате подобные задачи в любой другой роли.

Тоесь сначала вы пишите технический контракт API а потом уже реализацию. Очень верятно что это будет цикл: получил фидбек — улучшил.

Я например в какой-то момент задолбался обьяснять слишком удаленным от меня программерам (в nearshoring) что нельзя просто так взятъ и поменять api. Теперь им из Open API генерится библиотека содержащая Java Interafaces in Value Objects, все версионированно. Ошибки конечно ещё можно сделать но хотябы тип возвращаемого или поличемого обьекта не меняется больше без предупреждения и т.д.

Но Куда важнее другая тема. Имея представление о API в техническом формате мы смогли ускорить разработчиков клиентского приложения. Их команда смогла на 6-9 месяцев раньше начать писать их приложение и давать нам фидбек к нашему API которое которое на тот момент сущёствовало только как Open API без написаных сервисов.