api: openapi specification generation

* Adds CLI to generate OpenAPI spec out of docstrings.

* Adds initial test to validate spec.

* Adds Marshmallow validation for `/jobs` POST endpoint.

Signed-off-by: Diego Rodriguez <diego.rodriguez@cern.ch>

.gitignore

@@ -78,3 +78,6 @@ target/
 
 # Vagrant
 .vagrant
+
+# OpenAPI
+openapi.json

MANIFEST.in

@@ -23,6 +23,7 @@ include COPYING
 include *.rst
 include *.sh
 include pytest.ini
+include docs/openapi.json
 recursive-include reana_job_controller *.json
 recursive-include docs *.py
 recursive-include docs *.png

docs/conf.py

@@ -51,6 +51,7 @@
     'sphinx.ext.intersphinx',
     'sphinx.ext.viewcode',
     'sphinxcontrib.httpdomain',
+    'sphinxcontrib.openapi'
 ]
 
 # Add any paths that contain templates here, relative to this directory.

docs/gettingstarted.rst

@@ -10,3 +10,12 @@ Complex example
 ---------------
 
 FIXME
+
+CLI
+---
+
+The REANA Job Controller package offers the possibility to create its OpenAPI specification file using the Flask CLI.
+
+.. code-block:: console
+
+   $ FLASK_APP=reana_job_controller/app.py flask openapi create openapi.json

docs/restapi.rst

@@ -1,17 +1,4 @@
 REST API
 ========
 
-GET /jobs
----------
-
-.. autofunction:: reana_job_controller.app.get_jobs
-
-POST /jobs
-----------
-
-.. autofunction:: reana_job_controller.app.create_job
-
-GET /jobs/<job_id>
-------------------
-
-.. autofunction:: reana_job_controller.app.get_job
+.. openapi:: openapi.json