Блог

Главная - Вопросы по программированию - Для OpenAPI (swagger-php), как мне автоматически генерировать параметры запроса?

Для OpenAPI (swagger-php), как мне автоматически генерировать параметры запроса?

#php #swagger #openapi #swagger-php

#php #swagger #openapi #swagger-php

Вопрос:

Я пишу спецификацию OpenAPI и пытаюсь автоматически сгенерировать возможные параметры запроса (используя swagger-php) из аннотаций для маршрута запроса. Я знаю, что могу просто ввести все возможные параметры для каждого маршрута, но мне действительно нужно иметь возможность автоматически генерировать возможные параметры из свойств класса, используя аннотации, как я могу сделать для тела запроса. (У нас будет множество классов / путей, и обновление их, скорее всего, не произойдет, если они не будут сгенерированы так, как это может быть в теле запроса / JsonContent. Возможно ли это с помощью swagger-php или даже OpenAPI в целом?

Я получил это для работы с put и телом запроса, но как мне сделать это для запроса get, который все еще использует свойства класса?

Я могу сделать это для тела запроса:

     /**
     * @return Response
     *
     * * @OAPut(
     *     path="/persons",
     *     tags={"Person"},
     *     @OARequestBody(
     *          request="person",
     *          required=false,
     *          description="Optional Request Parameters for Querying",
     *          @OAJsonContent(ref="#/components/schemas/Person")
     *      ),
     *     @OAResponse(
     *          response="200",
     *          description="Returns matching Person Object",
     *          @OAJsonContent(
     *              type="array",
     *              @OAItems(ref="#/components/schemas/Person")
     *          )
     *     )
     * )
     */

Запись каждого параметра для более чем 30 классов не будет поддерживаться:

      /** @OAGet(
     *     path="/events",
     *     tags={"Events"},
     *     @OAParameter(
     *          name="eventID",
     *          in="query",
     *          required=false,
     *          description="The event ID specific to this event",
     *          @OASchema(
     *              type="string"
     *          ),
     *     ),
    *
   * ....etc

Комментарии:

1. Не используйте этот путь. Строки аннотаций, как правило, превышают размер метода, который они описывают, а язык не самый выразительный. Разработчики, как правило, ненавидят этот код, поскольку он не читается.

2. На самом деле я главный разработчик (на данный момент) и чувствую, что наличие этого в комментариях означает, что это действительно может оставаться актуальным. Вот почему я пытаюсь автоматически извлекать параметры запроса из свойств, как я могу с телом запроса. Это должно, по крайней мере, гарантировать актуальность состояния детали с минимальными усилиями, верно? Вы хотите сказать, что это не может быть сделано автоматически? Или просто вы бы не рекомендовали это? В любом случае, что бы вы порекомендовали тогда?

Ответ №1:

Swagger-PHP требует аннотаций для документирования параметров запроса. Вы можете несколько уменьшить дублирование кода, добавив @OAParameter аннотации верхнего уровня, на которые можно ссылаться с помощью $ref="#/components/parameters/PARAM_NAME" , как показано здесь и здесь.

 /**
 * @OAParameter(
 *   parameter="eventID_in_query",
 *   name="eventID",
 *   description="The event ID specific to this event",
 *   @OASchema(
 *     type="string"
 *   ),
 *   in="query",
 *   required=false
 * )
 */

...

     /** @OAGet(
     *     path="/events",
     *     tags={"Events"},
     *     @OAParameter(ref="#/components/parameters/eventID_in_query"),