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

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

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

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

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

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

Есть ли способ сказать, что /user/ [POST] — это просто псевдоним /user/login [POST]?

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

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

Любые идеи ?


swagger swagger-ui swagger-php
person Growiel    schedule 29.12.2015    source источник

Ответы (2)


arrow_upward
4
arrow_downward

Использование ссылок уже возможно в 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() {
 }
person Bob Fanger    schedule 19.03.2016
comment
Несмотря на то, что я больше не использую swagger-php, я потратил время, чтобы проверить это, похоже, работает как положено. Отметить это как решенное. - person Growiel; 21.03.2016
comment
Я думаю, что это должно быть ref="#/paths/~1user~1login" - символ / в /user/login должен быть экранирован как ~1 при использовании в ссылках. - person Helen; 21.07.2017
comment
Поле ref является неожиданным полем для аннотации @SWG\Path для текущей версии swagger-php 2.0.12. Кроме того, кодирование / на ~1 не реализовано в swagger-php. - person Arno; 29.11.2017
comment
@Arno Я обновил ссылку в примере и выпустил swagger-php 2.0.13, который добавляет поле ссылки в @SWG\Path и реализует кодировку ~1. - person Bob Fanger; 01.12.2017
comment
@Bob Fanger Спасибо разработчику, я проверю ваше улучшение как можно скорее - person Arno; 01.12.2017

arrow_upward
0
arrow_downward

Используя Swagger 2.0, вы можете указать путь и избежать дублирования документации.

Пример:

{
  "swagger": 2.0,
  "info": {
    "version": "1.0.0",
    "title": "Pet"
  },
  "host": "localhost:1234",
  "schemes": [ "http" ],
  "paths": {
    "/pet": { "$ref": "#/paths/x-endpoint-pet" },
    "x-endpoint-pet" : {
        "post": { 
            "tags" : [ "pet" ] 
        }
    }
  }
}

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

Это, по крайней мере частично, связано с конкретным подходом к реализации, принятым в swagger-php. Реализация php меняет отношение собственный-владелец между path и операцией< /em> объекты.

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

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

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

person Mark    schedule 16.03.2016
comment
Ваш пример правильный. Не могли бы вы упомянуть, что путь x-endpoint-pet не содержит косой черты? Если путь содержит косую черту, вы должны закодировать косую черту ~1 - person Arno; 29.11.2017