同一方法的两条路径 [英] Two paths for the same method

问题描述

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

Been trying to use Swagger to generate my documentation for my PHP Rest API, using swagger-php.

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

It's working pretty great, not quite sure if I'm a fan of having huge comment blocks due to the documentation, but that's not the issue.

我有两条路径:

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

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

Both of them call the same method in my PHP code: login().

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

Is there a way for me to say that /user/ [POST] is just an alias of /user/login [POST] ?

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

I'd like both of them to be present in the list of Operations, complete with their documentation and saying that they do the same thing, just with a different path to provide options to the user.

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

I could of course copy-paste the comment block, but I really don't want a 50 lines comment block for a one line method that just calls another method.

有什么想法吗?

推荐答案

通过使用 @SWG\Path，已经可以在 swagger-php 中使用引用.

Using references is already possible in swagger-php by using the @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 文档中公开别名.

But remember that swagger is to document your API, if /user/login is the canonical API endpoint for logging in I wouldn't even expose the alias in the swagger docs.

@Mark 在 swagger-php 中，path 仍然拥有 操作，但它使用 一些技巧来自动创建@SWG\Path，这避免了作为一般用途的样板案例是为每个 php 方法记录一个 http 方法，但如果您的方法处理多个 http 方法，则直接使用 @SWG\Path 可能会更短:

@Mark In swagger-php the path still owns the operations, but it uses some tricks to create the @SWG\Path automatically, this avoids boilerplate as the general use case is to document one http-method per php method, but if your method handles multiple http-methods it might be shorter to use @SWG\Path directly:

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

这篇关于同一方法的两条路径的文章就介绍到这了，希望我们推荐的答案对大家有所帮助，也希望大家多多支持IT屋！