同一方法的两条路径

Question

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

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

我有两条路：

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

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

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

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

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

有什么想法吗？

Answer 1

使用 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 实现反转 own-owned 与 path 之间的关系] 和 operation 对象。

在 Swagger 2.0 规范中 path 拥有 operation，一个路径可以引用其他路径。

在 swagger-php 实现中 operation 拥有 path。这会给人一种错误的印象，即 operation 可以有别名 and/or 拥有多个路径.

这是一个概念性问题，可能会在 swagger-php 的未来版本中解决。

Answer 2

通过使用 @SWG\Path.

，在 swagger-php 中已经可以使用引用了

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

但请记住，swagger 是 document 你的 API，如果 /user/login 是用于登录的规范 API 端点，我不会甚至不要在大摇大摆的文档中公开别名。

@Mark In swagger-php path 仍然拥有 operations，但它使用 some tricks自动创建 @SWG\Path，这避免了样板文件，因为一般用例是为每个 php 方法记录一个 http 方法，但如果您的方法处理多个 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() {
 }

同一方法的两条路径

Two paths for the same method

swagger

swagger-ui

swagger-php