Two paths for the same method

问题:

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 ?

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

回答2:

Using Swagger 2.0 you can reference a path and avoid duplicating the documentation.

Example:

{
  "swagger": 2.0,
  "info": {
    "version": "1.0.0",
    "title": "Pet"
  },
  "host": "localhost:1234",
  "schemes": [ "http" ],
  "paths": {
    "/pet": { "$ref": "#/paths/x-endpoint-pet" },
    "x-endpoint-pet" : {
        "post": { 
            "tags" : [ "pet" ] 
        }
    }
  }
}

swagger-php as of version 2.0.6 doesn't support such references however.

This is at least partially due to the specific implementation approach taken in swagger-php. The php implementation reverses the own-owned relation between the path and the operation objects.

In the Swagger 2.0 spec the path owns the operation, and a path can reference other paths.

In the swagger-php implementation however the operation owns the path. This then gives the wrong impression that an operation can have aliases and/or own multiple paths.

This is a conceptual issue which will likely be addressed in a future version of swagger-php.