Autodocumentation of mobile web services on the example of Yii

I think that many, especially small companies, when working with the same framework, constantly write some things / extensions, etc. that solve exactly the tasks that they encounter most often.

In our case, this framework is Yii, and one of the most popular problems was the simultaneous development of a web service for iOS / Android applications.

At first, as always, the developers simply agreed among themselves what and how, but if the developer suddenly changed, the problems started. Next is a description of the input / output data in the wiki. With a large number of minor changes, there was a problem of synchronization of the code and formats described in the wiki.
')
How we solved the problem - below.

Development of a web service controller

As a rule, a mobile service is a separate project module. We made a basic module and a basic controller for working with a web service.

Key things below.

class VMJsonServiceController extends CController { public $documentationMode = false; protected $request = null; ... public function init() { if ($this->documentationMode) { return; } if (Yii::app()->request->isPostRequest) { $json = CJSON::decode(file_get_contents("php://input"), false); if (isset($json->request)) { $this->request = $json->request; } else { $this->respondWithError(VMServiceResponseCode::SERVICE_ERROR, 'There is no request node'); } } else { ... } } ... public function checkInputParameters($params = array()) { if ($this->documentationMode) { $exception = new VMDocumentationException(); $exception->parameters = VMObjectUtils::fromArray($params); throw $exception; } $this->checkObjectParameter($params, $this->request); } ... } 

The most "salt" is precisely in the $documentationMode parameter, but more on that later.
Now we will consider an example of the controller from a real project, and not from a common library.

 class UsersController extends VMJsonServiceController { ... public function actionSignUp() { $this->checkInputParameters(array( 'user' => array( 'email' => 'test@test.com', 'password' => '12345', 'phone' => array('optional', 'value' => '+7 999 998 76 54'), 'photos' => array('array', 'value' => array( 'file' => base64_encode('Image'), ) ) )); $email = $this->request->user->email; ... } ... } 

The checkInputParameters method checks that the data came in the correct format for this method (email and password are required, phone is optional, and photos is an array of data. Next, we are sure that we have all the necessary data and can work with them.

Now, actually, what was discussed at the beginning of the article is about documentation. In principle, the array in the checkInputParameters method is the input data format, and, in fact, we generate documentation on the basis of it, but constantly generating it with pens is uninteresting and time consuming. Therefore, we will force the module to generate documentation about itself.

1. Making another controller
With the Metadata extension, it bypasses all controllers and Actions, and then renders a visual representation of the method parameters and service responses. This is done using the checkInputParameters method mentioned checkInputParameters

 class VMDocumentationController extends CController { ... //     ,      //     ""    private function getDefinition($class, $method) { try { $class->{$method}(); } catch (VMDocumentationException $e) { return (object) array( 'parameters' => $e->parameters ); } } ... } 

2. The code of the base module is correct

 class VMJsonServiceModule extends CWebModule { public function init() { ... $this->controllerMap = array( 'documentation' => array( 'class' => 'VMDocumentationController' ) ); } } 

What does this give us? And the fact that the iOS / Android programmer for the same url has documentation for any project, only the baseUrl changes.
What does the documentation look like?
A couple of screenshots below.

In the top navbar there is a list of all the controllers of the modules, in the left one there is a list of all actions of the controller. Optional parameters can be removed from the request, the Call button will send the request and show the server response. That is, you can not write a single line of code, but test the work of the web service on any input data.





And finally - all source codes can be found here . In some places, the code is terrible, in some places it is very terrible, a lot of what is in our library besides the mobile service - nobody needs it, but if there is something to offer, pull-request to help you.

Thanks for attention