Two paths for the same method

Question

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.

I have two paths:

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

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

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.

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.

Any ideas ?

Answer 1

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

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