Home Development of Websites Autodocumentation of mobile web services using Yii as an example

Autodocumentation of mobile web services using Yii as an example

by admin

I think a lot of companies, especially small ones, when working with the same framework, are constantly writing some thing/extensions, etc. that solve exactly the tasks 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 apps.
At first, as always, just the developers agreed among themselves what and how, but if the developer suddenly changed – problems began. Next – the description of the input/output data in the wiki. With a lot of small changes it was a problem to synchronize the code and formats described in the wiki.
How we solved the problem is below.

Web service controller development

As a rule, a mobile service is a separate module of the project. Made a base module and base controller to work with the web service.
The key things are 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 exactly in the parameter $documentationMode but more about that later.
Now let’s look at an example controller from a real project, not from a shared 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 method checkInputParameterschecks that the data came in the right format for this method (email and password are mandatory, phone is optional, and photos is an array of data. Next, we are sure that we have all necessary data and we can work with it.
Now, what we were talking about at the beginning of the article – the documentation. In principle, the array in method checkInputParameters – is the format of input data, and, in fact, on the basis of it we generate documentation, but constantly generate it manually – not interesting and long. So, let’s make the module generate documentation of itself.
1. Making another controller
Using the extension Metadata it bypasses all controllers and Actions, and then renders a visual representation of the method parameters and service responses. This is done using the above mentioned method checkInputParameters

class VMDocumentationController extends CController{...//See the complete code in the repository.//It takes the object "controller" and the name of the methodprivate function getDefinition($class, $method){try {$class-> { $method}();} catch (VMDocumentationException $e) {return (object) array('parameters' => $e-> parameters);}}...}

2. Correcting the code of the base module

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

What does this give us? And that by the same url the iOS/Android programmer has documentation for any project, only the baseUrl changes.
What does the documentation look like?
A couple of screenshots below.
In the upper nabbar is a list of all module controllers, in the left is a list of all controller actions. Optional parameters can be removed from the request, the Call button will send the request and show the server’s response. That is you can not write a line of code, but test the web service on any input data.
Autodocumentation of mobile web services using Yii as an example
Autodocumentation of mobile web services using Yii as an example
Autodocumentation of mobile web services using Yii as an example
And finally, you can find all the source codes here Sometimes the code is horrible, sometimes very horrible, a lot of things which are in our library, except the mobile service – no need in hell, but if you have something to offer – pull-request will help you.
Thank you for your attention

You may also like