问题描述
一直在尝试使用 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() {
}
这篇关于同一方法的两条路径的文章就介绍到这了，希望我们推荐的答案对大家有所帮助，也希望大家多多支持！