swagger - 同一方法的两条路径

Question

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

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

我有两条路:

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

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

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

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

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

有什么想法吗？

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

但请记住，swagger 是为了记录您的 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() {
 }