Где можно посмотреть все типпы аннотаций для swagger php?

Question

[Sergey Ilichev]

Всем привет коллеги)

Подскажите, кто пользовался сваггером, где можно найти документацию по всем аннотациям? Возможно я просто не могу найти на их официальном сайте, но я там много разделов с документацией перерыл и везде только просто говорится о том, как руками или через эдитор составить json, а как его на основе аннотаций составить? Там описывается кодогенератор, но опять же я и так знаю, как его использовать, а вот список всех доступных аннотаций найти не получилось пока.

Если что я себе установил расширение zircote/swagger-php для работы со свагером в php yii2 фреймворке. Там есть примеры с аннотациям, но не все описывается. Например как нормально формировать поля response без ссылки #ref на schema, а описывая их полностью в самом методе?

В общем есть ли какая-то документация со всеми аннотациями? Они ведь не зависят от используемого языка и расширения? Или зависят?

Answer 1

[Sergey Ilichev]

В общем ответа как такового нет, нужно искать примеры аннотаций на форумах, в разных расширениях для фреймворков, ну и методом тыка изучать. Если лень так делать, лучше сразу начинайте писать документацию по openApi спецификации в swagger editor, а потом этот файл кладите в swagger ui и пользуйтесь. Потому что для openApi хотя бы документации много есть.

Comments

[Дмитрий Свиридов]

Насчёт "лучше" - не согласен. Почему - написал в комментариях под своим ответом. :)
Единственный плюс написания вручную - это то, что не надо разбираться с аннотациями этой библиотеки. Но минусы, на мой взгляд, сильно более весомые, особенно когда эндпоинтов становится много.

Answer 2

[Сергей delphinpro]

Swagger использует спецификацию OpenAPI (2 или 3 версии)
Есть на русском https://starkovden.github.io/step5-components-obje...

Comments

[Sergey Ilichev]

А там точно есть аннотации php? Меня интересует именно посмотреть аннотации для php, а не делать руками готовый json. По ссылкам, которые вы отправили, я не вижу аннотаций с @OA. Там примеры для написания через. swagger editor.

[Sergey Ilichev]

Ни уже ли нет документации, как именно писать php аннотации? Чтобы просто все аннотации были подробно разобраны, вот такой объект в аннотациях так создать, а такой так, а можно сделать вложенные объекты через аннотации так, а сделать один код ответа для нескольких респонсов через аннотации так. Зачем вообще мне этот эдитор, если я из кода хочу генерировать. А у swagger в официальной документации к генератору вообще нет никакой нормальной документации.

Answer 3

[Дмитрий Свиридов]

Прямо списка доступных аннотаций я тоже не нашёл, но там есть вообще папка с примерами, где есть многие вещи.

По поводу генерации: вам нужно сделать эндпоинт, в котором будет выполняться следующий код:

$openapi = \OpenApi\Generator::scan(['/path/to/project']);
header('Content-Type: application/x-yaml');
echo $openapi->toYaml();

При обращении к этому эндпоинту библиотека просканирует ваш проект, ища в нём аннотации и сформирует yaml. Если что-то не так - увидите ошибку.

Comments

[Sergey Ilichev]

Привет! С генерацией я разобрался, но спасибо за ответ. Вот с аннотациями дело туго пока. Да, примеры в самой библиотеке есть, но вот вчера например столкнулся с необходимостью написать аннотации, чтобы для одного кода ответа было несколько вариантов ответов, то есть api всегда отвечает 200 ок, но при этом сообщение ответа меняется. Вот как это сделать через аннотации беспонятия и примеров пока не нашел.

[Sergey Ilichev]

такое ощущение, что у них основная задумка не генерировать код автоматически по аннотациям, а писать его в editor вручную, потому что описания json куча, а вот аннотаций вообще нет. Зачем тогда этот инструмент нужен, если ты автоматически не можешь генерировтаь документацию удобно?)

[Дмитрий Свиридов]

Sergey Ilichev, как-то так:

*     @OA\Property(property="resp", type="object", anyOf = {
 *          @OA\Schema(ref="#/components/schemas/Variant1"),
 *          @OA\Schema(ref="#/components/schemas/Variant2")
 *     })

[Sergey Ilichev]

Дмитрий Свиридов, а это все должно быть обвернуто в @OA\Response? И вот еще интересно, схемы ведь можно описывать без ref? Она просто не переиспользуется.

[Sergey Ilichev]

Дмитрий Свиридов, я так полагаю, что @OA\Response просто должен быть обязательным для \OA\Post|Get и всех запросов? То есть типа property должно быть частью объекта response.

[Sergey Ilichev]

Дмитрий Свиридов, или тут наоборот @OA\Property(property="resp", type="object", anyOf = { это просто свойство объекта @OA\Post\Get и содержит в себе схемы @OA\Response?

[Sergey Ilichev]

Дмитрий Свиридов, попробовал и так и так, чет не работает. Если делать этот код

*      @OA\Property(property="resp", type="object", anyOf = {
 *          @OA\Schema(ref="#/components/schemas/Variant1"),
 *          @OA\Schema(ref="#/components/schemas/Variant2")
 *     })

частью объекта @OA\Response, то генерится вот такой yaml

responses:
        '200':
          description: wqewq

Вот пример аннотации

*   @OA\Response(
     *     response=200,
     *     description="wqewq",
     *     @OA\Property(
     *       property="resp",
     *       type="object",
     *       anyOf = {
     *         @OA\Schema(
     *           type="array",
     *           @OA\Items(
     *             @OA\Property(
     *               property="guid",
     *               type="string",
     *               example="548112d7-7fb7-417b-916a-76fb74de8fba",
     *               description="The transaction was successfully created",
     *             )
     *           )
     *         ),
     *
     *       }
     *     )
     *   ),

Причем тут даже не понятно как еще сюда добавить объект так, чтобы схема с типом array, была json. Это наверно нужно вообще сначала все оборачивать в @AO\MediaType json, а потом только схема с типом array и итемами?

[Дмитрий Свиридов]

Sergey Ilichev, у меня вот так сделано.
Респонс (у меня он универсальный для всех типов ответа, поэтому через ApiResult):

*     @OA\Response(
     *      response=200,
     *      description="ok",
     *      @OA\JsonContent(
     *                 allOf = {
     *                     @OA\Schema(ref="#/components/schemas/ApiResult")
     *                 },
     *                 @OA\Property(
     *                     property = "success",
     *                     type="boolean",
     *                     example="true"
     *                 ),
     *              @OA\Property(
     *                  property = "data",
     *                  ref="#/components/schemas/Item"
     *             )
     *      )
     *    ),

Item:

/**
 * @OA\Schema(
 *     schema="Item",
 *     description="Блабла",
 *     @OA\Property(property="id", type="integer", example=123),
 *     @OA\Property(property="name", type="string", example="Test"),
*     @OA\Property(property="var", type="object", anyOf = {
 *          @OA\Schema(ref="#/components/schemas/Variant1"),
 *          @OA\Schema(ref="#/components/schemas/Variant2")
 *     })
 * )
 */

[Дмитрий Свиридов]

Sergey Ilichev, но соглашусь с вами, что эти комменты для OpenAPI - весьма неочевидная вещь. Я доку писал методом проб и ошибок, так сказать. Но других способов для PHP я не нашёл)

[Sergey Ilichev]

Дмитрий Свиридов,

А что такое ApiResult и почему он в allOf? Можно скриншот того, как у вас выглядит интерфейс ответа? Там как-то должно выбираться из списка?

У меня получается такой интерфейс, при том что я описываю два ответа в allOf



А вот моя аннотация для ответов

*   @OA\Response(
     *     response=200,
     *     description="Ok",
     *     @OA\JsonContent(
     *        allOf = {
     *           @OA\Schema(
     *             type="array",
     *             @OA\Items(
     *               @OA\Property(
     *                 property="guid",
     *                 type="string",
     *                 example="548112d7-7fb7-417b-916a-76fb74de8fba",
     *                 description="The transaction was successfully created",
     *               )
     *             )
     *           ),
     *           @OA\Schema(
     *             @OA\Property(
     *              property="error",
     *              type="object",
     *              @OA\Property(
     *                property="code",
     *                type="string",
     *                example="101"
     *              ),
     *              @OA\Property(
     *                property="message",
     *                type="string",
     *                example="No input data"
     *              )
     *             )
     *           )
     *         }
     *     )
     *   ),

[Дмитрий Свиридов]

Sergey Ilichev, . allOf нужен, чтобы расширять ApiResult. В data у меня может быть и список, и объект, например, или вообще null.

[Sergey Ilichev]

Дмитрий Свиридов,

Сделал, как хотел, так чтобы переключать примеры ответов. Но теперь я не понимаю зачем нужно описание ответов с типами? Можно вообще удалить схемы для ответов, и ничего не поменяется, просто оставить примеры. Попробовал удалить, отправил запросы, все работает.



Пример ответа

*   @OA\Response(
     *     response=200,
     *     description="Ok",
     *     @OA\MediaType(
     *       mediaType="application/json",
     *       @OA\Schema(
     *         oneOf={
     *           @OA\Schema(
     *             type="array",
     *             @OA\Items(
     *               @OA\Property(
     *                 property="guid",
     *                 type="string",
     *                 description="Internal identificator of transaction",
     *               )
     *             )
     *           ),
     *           @OA\Schema(
     *             @OA\Property(
     *               property="error",
     *               type="object",
     *               @OA\Property(
     *                 property="code",
     *                 type="intager",
     *               ),
     *               @OA\Property(
     *                 property="message",
     *                 type="string",
     *               )
     *             )
     *           )
     *         },
     *       ),
     *       @OA\Examples(
     *         description="Success response",
     *         summary="Success response",
     *         example="Success response",
     *         value={{"guid":"548112d7-7fb7-417b-916a-76fb74de8fba"}}
     *       ),
     *       @OA\Examples(
     *         description="Response with code 101",
     *         summary="Response with code 101",
     *         example="Response with code 101",
     *         value={"error":{"code":"101", "message":"No input data"}}
     *       )
     *     )
     *   ),

[Дмитрий Свиридов]

Sergey Ilichev, по типам можно генерить API-клиенты, а по примерам - нет. Кроме того, в примере никак не укажешь, скажем, что максимально допустимое значение - это 100 (например). И т.п. То есть пример - это только пример значений и ничего больше.

[Sergey Ilichev]

Дмитрий Свиридов, вы имеете ввиду swagger ui? Я его сгенерил и с указанием схем и без указания схем, одно и то же. Работает и со схемами и без, при том, то что написано в примерах, может вообще не соотноситься с тем, что написано в схеме. То есть в Examples можно в value написать другие поля и типы, которых нет в схемах и все типа работает. Плюс я могу написать, допустим, для параметра guid длину 10 символов, а приходит в моем ответе 100 и все равно все работает и нигде ничего не пишется, что типа тип ответа получен не корректный. Где это вообще должно писаться? С параметрами для запроса, тут понятно, ты типа отправляешь не то и он пишет ошибку, а вот с валилидацией ответа чет не понятно.

[Дмитрий Свиридов]

Sergey Ilichev, если я правильно вас понял, то в этих аннотациях можно написать вообще всё, что угодно - и нет никакой гарантии, что это будет отражать реальное положение вещей. И дело, кстати, не в PHP. В том же NestJS, например, тоже можно сделать так, что схема не будет соответствовать реальному ответу.

[Sergey Ilichev]

Дмитрий Свиридов, еще на всякий случай проверил, если писать пример не в общих примерах examples, а прямо в схеме ответа, то тоже нет никакой проверки, пишешь в type = "integer", в примере {"guid":"wweqweqeqweq"}, и все валидно генерируется. Плюс если запрос отправляешь и указан для параметра, как у меня выше в примере, для code тип integer, а приходит строка, то тоже нет ошибок. Может для ответов схемы не нужны? Они не валидируются никак, туда можно писать что хочешь, хоть type="wqeqweqweq". В интерфейсе сгенерированном они не отображаются, заменяются примерами ответов из examples или из example в схеме, или из example в свойстве. Вдруг кому-нибудь пригодиться, поэтому напишу - приоритет у example такой -

- examples в mediaType, потом example в schema где описан oneOf, потом schema где тип array, потом у items и у property. То есть те, что выше, те имеют больший приоритет.

[Sergey Ilichev]

Дмитрий Свиридов,

Sergey Ilichev, если я правильно вас понял, то в этих аннотациях можно написать вообще всё, что угодно - и нет никакой гарантии, что это будет отражать реальное положение вещей. И дело, кстати, не в PHP. В том же NestJS, например, тоже можно сделать так, что схема не будет соответствовать реальному ответу.

похоже что так, или что-то не так описывается, то есть может нужно как-то по другому писать эти аннотации.

[Sergey Ilichev]

Дмитрий Свиридов, вопрос только тогда в том, зачем вообще что-то тут описывать, если можно просто написать examples для ответов и все)

[Sergey Ilichev]

Дмитрий Свиридов, единственный плюс, который я вижу в описании схем ответов, это возможность посмотреть эти схемы в интерфейсе, например так



На сколько это нужно, решать каждому, мне кажется для ответов это не особо важно. Ну будет там в ответе длина указана строки? Типа для того чтобы в базе оптимизировать хранение? Так-то сам по себе пример нест не особо меньше информации. Описание выходных параметров разве что, типа что вот вы получите guid и вот его описание. Хотя могли бы это добавить куда-то удобней. В тот же examples, чтобы для каждого ответа, для каждого параметра описывать description, ну и даже типы, раз в схемах ответов все равно ничего не проверяется ни при генерации, ни при запросе.

Кстати, на счет oneOf, anyOf, allOf, я почитал, по задумке это (если я правильно понимаю) должно указывать, что то, что возвращается в ответе, должно соответствовать одной, любой или всем схемам. Но по факту вроде там вообще никакого соответствия не проверяется со схемой.

[Дмитрий Свиридов]

Sergey Ilichev, потому что это документация. Она подразумевает под собой не только пример, но и модель данных и её ограничения. Например, возьмёт фронтендер, посмотрит на пример, а там число 100 написано в каком-то поле. Как он только по примеру поймёт, что там, например, может быть число строго больше нуля и меньше 101?

Но по факту вроде там вообще никакого соответствия не проверяется со схемой

Эта генерация документации через аннотации не гарантирует соответствия примера схеме или же соответствия тому, что реально в вашем коде происходит. Это нужно рассматривать просто как некий инструмент для формирования OpenAPI по комментариям в коде. Следить за его актуальностью нужно самостоятельно. Но никто не мешает, кстати, написать OpenAPI вручную (я раньше так и делал) без этой библиотеки, но, на самом деле, в таком случае расхождений получается сильно много - и быстро теряется актуальность.

[Sergey Ilichev]

Дмитрий Свиридов, наверно так и есть. Хотя можно сделать и так чтобы хотя бы ответ, который приходит при отправке запроса, проверялся бы по схеме) А то так понаписать можно всего что угодно)

Тоже думаю, что наверно проще написать в swagger editor документацию и положить в swagger ui.

Так хотя бы не нужно искать по разным сайтам как пользоваться аннотациями)

[Дмитрий Свиридов]

Sergey Ilichev, есть ещё вот такая штука https://github.com/justinrainbow/json-schema (это немного другое, но валидация будет).

[Дмитрий Свиридов]

Sergey Ilichev, "Тоже думаю, что наверно проще написать в swagger editor документацию и положить в swagger ui." - я выше писал, что так делал - уже ушёл от этого.

1. Во-первых, по мере роста проекта этот файл становится просто огромным - и в нём сложно ориентироваться.
   
2. Во-вторых, постоянно начинаются расхождения между этим файлом и валидаторами/сериализаторами в коде
   
3. В-третьих, при использовании этой библиотеки схемы можно держать прямо рядом с моделями и валидаторами - это уменьшает вероятность расхождений