Create API spec

[jtojnar]

We need machine readable API description. Among other things, it will allow us to check the implementation compliance automatically.

I tried to describe the API using OpenAPI 2 but it proved to be too limited. OpenAPI 3 looks more promising but the automated checking tooling does not seem to support it yet.

Depends on: apiaryio/dredd#894

[jtojnar]

Bootprint might be more straightforward to set-up than Swagger UI but it also does not support OpenAPI 3.0.

--- a/.gitignore
+++ b/.gitignore
@@ -1,3 +1,4 @@
+/_docs/website/api
 /data/favicons/*.png
 /data/favicons/*.jpg
 /data/thumbnails/*.png
--- a/gruntfile.js
+++ b/gruntfile.js
@@ -163,11 +163,20 @@
         }
     });
 
+    grunt.registerTask('docs:api', 'API documentation', function() {
+        var bootprint = require('bootprint')
+           .load(require('bootprint-openapi'))
+           .build('docs/api-description.json','api')
+           .generate()
+           .done(console.log);
+    });
+
     grunt.registerTask('client:install', 'Install client-side dependencies.', ['auto_install']);
     grunt.registerTask('server:install', 'Install server-side dependencies.', ['composer:install:no-dev:optimize-autoloader:prefer-dist']);
     grunt.registerTask('install', 'Install both client-side and server-side dependencies.', ['client:install', 'server:install']);
     grunt.registerTask('default', ['install', 'versionupdater', 'compress']);
     grunt.registerTask('version', ['versionupdater']);
+    grunt.registerTask('docs', ['docs:api']);
     grunt.registerTask('zip', ['compress']);
     grunt.registerTask('lint:client', 'Check JS syntax', ['eslint']);
     grunt.registerTask('cs:server', 'Check PHP coding style', ['composer:run-script cs']);
--- a/package.json
+++ b/package.json
@@ -7,6 +7,8 @@
     "url": "https://github.com/SSilence/selfoss.git"
   },
   "devDependencies": {
+    "bootprint": "^1.0.2",
+    "bootprint-openapi": "^1.1.0",
     "grunt": "^0.4.5",
     "grunt-auto-install": "^0.3.1",
     "grunt-cli": "^1.2.0",