Примеры значений в спецификации: ключи example и examples

[nixel2007]

Что есть сейчас

Ни example, ни examples в документ не попадают. Swagger UI подставляет в форму «Try it out» значения, выдуманные по типу схемы, — для строки это "string", для числа 0.

Как это устроено в springdoc

Одиночный пример — атрибут той аннотации, что описывает объект; именованные примеры — отдельная повторяемая аннотация:

@Schema(example = "abc-123")                    // поле, класс, схема параметра
@Parameter(example = "12345")                   // параметр
@Parameter(examples = @ExampleObject(name = "...", value = "...", summary = "..."))
@Content(examples = @ExampleObject(...))        // тело запроса и ответы

@ExampleObject живёт только внутри examples у @Parameter или @Content и несёт name, value, summary, externalValue.

Как это ложится на winow

springdoc	winow
@Parameter(example =)	&Пример("42") на параметре метода
@ExampleObject в @Content ответа	повторяемая аннотация с привязкой по коду, как у &Возвращает
@Schema(example =) на поле	своя аннотация на поле

Последняя строка один-в-один не переносится: в springdoc пример на поле — атрибут @Schema, а у winow аналога @Schema нет, схема поля собирается из аннотаций validate. Вешать атрибут не на что, значит на поле пример может быть только самостоятельной аннотацией.

Развилка, которую надо решить до реализации

swagger-core пишет одиночный example везде, включая Schema Object. В OpenAPI 3.1 в схеме одиночный example объявлен устаревшим в пользу examples — массива; в Parameter Object и Media Type Object оба ключа живы.

То есть «как в springdoc» и «правильно по 3.1» здесь расходятся. #124 в таких случаях выбирал 3.1: двоичное тело описано пустым объектом вместо format: binary, обнуляемость — списком типов вместо nullable. По той же логике на поле надо писать examples: [...], а на параметре и в ответе — example.

Типизация

В springdoc example всегда строка, а парсер решает, литерал это или JSON. У нас &Пример("42") на поле с &Тип("Число") должен дать в документе 42, а не "42". Разбирать либо по объявленному &Тип, либо как JSON с откатом на строку.

Смежное

Значение по умолчанию — #132. Для параметров операции оно выводится из сигнатуры и аннотации не требует, а для полей типа — требует, как и пример.

🤖 Generated with Claude Code