Add api documentation

* Update version in package.json
* Move apidoc config to external file
* Add gulp task for apidoc
* Fix auth/userinfo path

apidoc.json

+{
+  "name": "grade@sfedu API",
+  "version": "0.1.0",
+  "url" : "http://grade.sfedu.ru/",
+  "title": "REST API of sfedu grade system",
+  "description": "Описание API БРС ЮФУ."
+}

gulpfile.js

@@ -3,6 +3,7 @@ var minimist = require('minimist');
 var fs = require('fs');
 var lazypipe = require('lazypipe');
 var babel = require('gulp-babel');
+var apidoc = require('gulp-apidoc');
 
 // command line arguments
 var varg = minimist(process.argv.slice(2), {
@@ -266,3 +267,11 @@ gulp.task('install', [
     'config',
     'default'
 ]);
+
+gulp.task('apidoc', function(done){
+    apidoc({
+        src: "~dev_rating/application/classes",
+        dest: "apidoc/",
+        config: "./"
+    },done);
+});

package.json

 {
   "name": "GradeRatingSystem",
-  "version": "0.0.0",
+  "version": "1.2.0",
   "devDependencies": {
     "babel-preset-es2015": "^6.9.0", 
     "babel-preset-es2015-without-strict": "0.0.2",
@@ -13,13 +13,9 @@
     "gulp-less": "^3.1.0",
     "gulp-minify-css": "^1.2.4",
     "gulp-uglify": "^1.5.3",
+    "gulp-apidoc": "^0.2.4",
     "lazypipe": "^1.0.1",
     "minimist": "^1.2.0",
     "through": "^2.3.8"
-  },
-  "apidoc": {
-    "url" : "http://grade.sfedu.ru",
-    "title": "REST API of sfedu grade system",
-    "description": "Описание API БРС ЮФУ."
   }
 }

~dev_rating/application/classes/Controller/Api/V0/Auth.php

@@ -3,10 +3,13 @@
 class Controller_Api_V0_Auth extends Controller_Handler_Api
 {
     /**
-     * @api {get} api/v0/auth/login?token=:token&login=:login&password=:password Check authorisation and get user info
-     * @apiParam {String} [token] Api key
-     * @apiParam {String} [login] User's login
-     * @apiParam {String} [password] User's password
+     * @api {get} api/v0/auth/userinfo?token=:token&login=:login&password=:password Check authorisation and get user info
+     * @apiName Get user info
+     * @apiGroup Auth
+     * @apiVersion 0.1.0
+     * @apiParam {String} token Api key
+     * @apiParam {String} login User's login
+     * @apiParam {String} password User's password
      */
     public function action_get_userinfo() {
         if ( !$this->user->isAdmin() ) // ToDo: we should use apikey mask for checking rights

~dev_rating/application/classes/Controller/Api/V0/Department.php

@@ -2,6 +2,14 @@
 
 class Controller_Api_V0_Department extends Controller_Handler_Api
 {
+    /**
+     * @api {get} api/v0/department/idByName Map dep. name to dep. ID
+     * @apiName Get department id
+     * @apiGroup Department
+     * @apiVersion 0.1.0
+     * @apiParam {String} token Api key
+     * @apiParam {String} name Department name
+     */
     public function action_get_idByName() {
         $name = $this->request->query('name');
 

~dev_rating/application/classes/Controller/Api/V0/Subject.php

@@ -4,9 +4,12 @@ class Controller_Api_V0_Subject extends Controller_Handler_Api
 {
     /**
      * @api {get} api/v0/subject/listForStudentID?token=:token&studentID=:studentID&semesterID=:semesterID Get list of student's subjects
-     * @apiParam {String} [token] Api key
-     * @apiParam {Int} [studentID] Student identifier
-     * @apiParam {Int} [semesterID] Semester identifier
+     * @apiName Get student's subjects
+     * @apiGroup Subject
+     * @apiVersion 0.1.0
+     * @apiParam {String} token Api key
+     * @apiParam {Int} studentID Student identifier
+     * @apiParam {Int} semesterID Semester identifier
      */
     public function action_get_listForStudentID() {
         if ( !$this->user->isAdmin() ) // ToDo: we should use apikey mask for checking rights

~dev_rating/application/classes/Controller/Api/V0/Teacher.php

@@ -33,6 +33,22 @@ class Controller_Api_V0_Teacher extends Controller_Handler_Api
         return $data;
     }
 
+    /**
+     * @api {put} api/v0/teacher Add new teacher(s)
+     * @apiName Add new teacher
+     * @apiGroup Teacher
+     * @apiVersion 0.1.0
+     * @apiParam {String} token Api key
+     * @apiParam {String} [batch] Flag about massive addition
+     * @apiParam {String} firstName
+     * @apiParam {String} secondName
+     * @apiParam {String} lastName
+     * @apiParam {String} departmentName
+     * @apiParam {String} [departmentID]
+     * @apiParam {String} jobPositionName
+     * @apiParam {String} [jobPositionID]
+     * @apiParam {String} status
+     */
     public function action_put_index() {
         try {
             if ( $this->request->query('batch') !== NULL ) {