Swagger 同一方法的两条路径

我一直在尝试使用Swagger PHP为我的PHP Rest API生成文档

它工作得非常好，不太确定我是否喜欢因为文档而有大量的评论块，但这不是问题所在

我有两条路：

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

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

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

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

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

---

有什么想法吗？

使用

Swagger 2.0

可以引用路径，避免重复文档

示例：

{ “招摇过市”：2.0， “信息”：{ “版本”：“1.0.0”， “头衔”：“宠物” }, “主机”：“本地主机：1234”， “方案”：[“http”]， “路径”：{ “/pet”：{“$ref”：“#/path/x-endpoint-pet”}， “x-endpoint-pet”：{ “职务”：{ “标签”：[“宠物”] } } } } 但是，从版本

2.0.6

开始，不支持此类引用

这至少部分是由于在

swagger php

中采用了特定的实现方法。php实现反转了路径和操作对象之间的自有关系

在

Swagger 2.0

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

然而，在

swagger php

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

---

这是一个概念性问题，可能会在未来版本的

swagger-php

中解决

通过使用

@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就是要记录你的API，如果/user/login是登录的规范API端点，我甚至不会在swagger文档中公开别名

@在swagger php中标记path仍然拥有操作，但它用于自动创建

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

---

尽管我不再使用招摇过市的php了，但我还是花了时间来测试它，似乎工作正常。将此标记为已解决。我认为它应该是

ref=“#/paths/~1user~1login”

，

/user/login

中的字符

/

在引用中使用时必须是

~1

。对于当前版本的swagger php 2.0.12，

ref

字段是@SWG\Path注释的意外字段。此外，swagger中没有实现/by~1的编码-php@Arno我已经更新了示例中的ref并在swagger php 2.0.13中发布，它将ref字段添加到@SWG\Path并实现~1编码。@Bob Fanger Thx对于开发人员，我将尽快检查您的改进您的示例是否正确。请注意，

x-endpoint-pet

路径不包含斜杠？如果路径包含斜杠，则必须按

~1

/**
 * @SWG\Path(
 *   path="/example",
 *   @SWG\Get(response=200, description="OK"),
 *   @SWG\Post(response=200, description="OK"),
 *   @SWG\Put(response=200, description="OK")
 * )
 */
 function thisMethodHandlesGetPostAndPutRequests() {
 }