2

一直在尝试使用 Swagger 为我的 PHP Rest API 生成文档，使用 swagger-php。

它工作得非常好，不太确定我是否喜欢由于文档而拥有大量评论块，但这不是问题。

我有两条路：

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

它们都在我的 PHP 代码中调用了相同的方法：login()。

我有没有办法说 /user/ [POST] 只是 /user/login [POST] 的别名？

我希望他们两个都出现在操作列表中，并附上他们的文档，并说他们做同样的事情，只是用不同的路径向用户提供选项。

我当然可以复制粘贴注释块，但我真的不希望一个 50 行的注释块用于只调用另一种方法的单行方法。

有任何想法吗 ？

4

2 回答 2

4

通过使用@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自动创建，这避免了样板，因为一般用例是为每个 php 方法记录一个 http-method，但是如果您的方法处理多个 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() {
 }
于 2016-03-19T16:40:12.507 回答
0

使用Swagger 2.0您可以引用路径并避免重复文档。

例子：

{
  “招摇”：2.0，
  “信息”：{
    “版本”：“1.0.0”，
    “标题”：“宠物”
  },
  “主机”：“本地主机：1234”，
  “方案”：[“http”]，
  “路径”：{
    "/pet": { "$ref": "#/paths/x-endpoint-pet" },
    “x-端点宠物”：{
        “邮政”： {
            “标签”：[“宠物”]
        }
    }
  }
}

但是， swagger-php的版本2.0.6不支持此类引用。

这至少部分是由于采用了特定的实现方法swagger-php。php 实现反转了路径和操作对象之间的拥有关系。

在Swagger 2.0规范中，路径拥有操作，路径可以引用其他路径。

然而，在swagger-php实现中，操作拥有路径。这会给人一种错误的印象，即操作可以有别名和/或拥有多个路径。

这是一个概念性问题，可能会在swagger-php.

于 2016-03-16T17:44:30.227 回答