Два пути для одного метода

Я пытался использовать Swagger для генерации моей документации для моего PHP Rest API, используя swagger-php.

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

У меня есть два пути:

/user/ [POST]
/user/login [POST]

Они оба вызывают один и тот же метод в моем PHP-коде: login().

Могу ли я сказать, что /user/ [POST] это просто псевдоним /user/login [POST]?

Я хотел бы, чтобы они оба присутствовали в списке операций, вместе с их документацией и сообщая, что они делают то же самое, просто с другим путем предоставления опций пользователю.

Конечно, я мог бы скопировать и вставить блок комментария, но я действительно не хочу, чтобы 50-строчный комментарий был для однострочного метода, который просто вызывает другой метод.

Есть идеи?

Источник

2 ответа

Решение

Использование ссылок уже возможно в swagger-php с помощью @SWG\Path,

/**
 * @SWG\Post(
 *   path="/user/login",
 *   @SWG\Response(response=200, description="OK")
 * )
 * @SWG\Path(path="/user/", ref="#/paths/user~1login");
 */
function login() {
  ...
}

Но помните, что swagger предназначен для документирования вашего API, если /user/login является канонической конечной точкой API для входа в систему, я бы даже не раскрыл псевдоним в документах swagger.

@Mark В swagger-php путь все еще принадлежит операциям, но он использует некоторые приемы для создания @SWG\Path автоматически это исключает шаблон, так как в общем случае документируется один http-метод для каждого php-метода, но если ваш метод обрабатывает несколько http-методов, его использование может быть короче @SWG\Path непосредственно:

/**
 * @SWG\Path(
 *   path="/example",
 *   @SWG\Get(response=200, description="OK"),
 *   @SWG\Post(response=200, description="OK"),
 *   @SWG\Put(response=200, description="OK")
 * )
 */
 function thisMethodHandlesGetPostAndPutRequests() {
 }
Источник

С помощью Swagger 2.0 Вы можете ссылаться на путь и избегать дублирования документации.

Пример:

{
  "чванство": 2,0,
  "Информация": {
    "версия": "1.0.0",
    "title": "Pet"
  },
  "host": "localhost:1234",
  "схемы": [ "http" ],
  "пути": {
    "/pet": { "$ref": "#/paths/x-endpoint-pet" },
    "x-endpoint-pet": {
        "сообщение": { 
            "tags": ["pet"] 
        }
    }
  }
}

swagger-php от версии 2.0.6 однако не поддерживает такие ссылки.

Это, по крайней мере, частично из-за конкретного подхода к реализации, принятого в swagger-php, Реализация php меняет отношение, принадлежащее собственному владельцу, между путем и объектами операции.

в Swagger 2.0 spec, путь владеет операцией, и путь может ссылаться на другие пути.

в swagger-php реализация, однако, операция владеет путем. Это тогда создает неправильное впечатление, что операция может иметь псевдонимы и / или иметь несколько путей.

Это концептуальный вопрос, который, вероятно, будет рассмотрен в будущей версии swagger-php,

Источник
Другие вопросы по тегам