Использовали ли Springfox или аналогичные инструменты для OpenAPI

Что проверяют

Знаете ли вы, как в Spring-проекте получить спецификацию API из кода и где это ломается. Уточняющий вопрос почти наверняка: почему Springfox сейчас не берут и что делать при переходе на Spring Boot 3.

Как отвечать

Сначала расставьте термины. OpenAPI это спецификация описания REST API (в ходу 3.0 и 3.1), Swagger это инструменты вокруг неё: Swagger UI, Editor, Codegen. Springfox и springdoc-openapi строят спецификацию по контроллерам Spring.

• Springfox: заброшен, последний релиз 3.0.0 вышел в 2020 году. Со Spring Boot 3 не работает из-за перехода на jakarta.*, а уже на Boot 2.6 падал из-за новой стратегии сопоставления путей, и лечили это spring.mvc.pathmatch.matching-strategy=ant_path_matcher. Настраивался бином Docket, аннотации Swagger 2: @Api, @ApiOperation, @ApiModelProperty;
• springdoc-openapi: стандарт сейчас. Стартер springdoc-openapi-starter-webmvc-ui (или -webflux-ui), спецификация на /v3/api-docs, интерфейс на /swagger-ui.html. Аннотации из io.swagger.v3.oas.annotations: @Tag, @Operation, @Schema, @Parameter, группы через бин GroupedOpenApi;
• миграция: @Api меняется на @Tag, @ApiOperation на @Operation, @ApiModelProperty на @Schema, Docket на GroupedOpenApi;
• design-first: спецификацию пишут первой, а интерфейсы контроллеров и DTO генерирует openapi-generator-maven-plugin. Документация тогда не расходится с кодом.

Расскажите свой опыт: какой подход, кто потреблял спецификацию (фронтенд, QA, партнёры), как закрывали Swagger UI на проде. Если со Springfox вы не сталкивались, это не минус: скажите, что брали springdoc, и объясните почему.

Где спотыкаются

Рассказывают про Springfox как про актуальный выбор. Для проекта на Boot 3 это сигнал, что опыт устарел.

Оставляют Swagger UI открытым на проде без авторизации. Выключается в профиле прода через springdoc.swagger-ui.enabled=false и springdoc.api-docs.enabled=false.

Считают, что аннотаций над методами достаточно. Спецификация без кодов 400 и 404, схемы ошибки и примеров мало помогает тем, кто пишет клиента.