Question

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

它工作得非常好，不太确定我是否因为文档而拥有巨大的评论块，但这不是问题。

我有两条路：

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

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

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

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

我当然可以复制粘贴注释块，但我真的不想为一行调用另一种方法的50行注释块。

有什么想法吗？

Answer 1

使用@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() {
  ...
}

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

@Mark在swagger-php中，路径仍然拥有操作，但它使用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() {
 }

Answer 2

使用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实现颠倒了路径与 操作<之间的自有关系/ em> 对象。

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

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

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

同一方法的两条路径

2 个答案: