zircote/swagger-php — pull request #101 by dave-newson (2013-08-13 05:38:02+00:00)
Title: Allow orphaned @SWG\Operations, resolvable by their nickname

This change will allow for "orphan" @SWG\Operation annotations to exist away from the Resource tree.
Once all files are parsed, orphans will be merged on top of elements in the Resource tree which have the same "unique" nickname.

The purpose of this change is to allow Routing-related annotations (resource::resourcePath, Api::path, operation::httpMethod) to exist away from description, parameter and return annotations, for systems where a router file exists separately to controller code. This makes life easier for developers who then can define the Swagger annotated paths within the routes files, and controller-related comments in the controller, making the annotations more DRY and exist where they belong, rather than one or the other.

An example of this notation, the following fixed resource path is defined in the router alongside the routing definition:
```
/**
* @SWG\Resource(
* resourcePath="/logs",
* @SWG\Api(
* path="/",
* @SWG\Operation(
* nickname="logs.index",
* httpMethod="GET"
* )
* )
* )
*/
```
The following orphaned Operation is then defined in the controller:
```
/**
* @SWG\Operation(
* nickname="logs.index",
* summary="This function does some magic xyz"
* )
*/
```
The parser recognises the orphan operation annotation and stores it for later. Once all files are parsed, the resource list is inspected for operations with the same nickname, and if found the operation in the resource tree will have it's elements overwritten with those from the orphan operation.

Empty elements are not written, so we don't entirely overwrite the original operation (eg. it's httpMethod).
If no nickname match is found, a notice is raised.

Orphans can overwrite multiple entries if the nicknames match. I thought about raising a notice for this, but it might be someone's intended functionality (multiple routes for one controller action?). As a result, the reunite function is slow because it crawls the entire registry for each orphan.