Merge 4637be7 into 9e9046f

MANIFEST.in

@@ -23,12 +23,14 @@ include COPYING
 include *.rst
 include *.sh
 include pytest.ini
+include docs/openapi.json
 prune docs/_build
 recursive-include docs *.py
 recursive-include docs *.png
 recursive-include docs *.rst
 recursive-include docs *.txt
 recursive-include reana_workflow_controller *.html
+recursive-include scripts *.py
 recursive-include tests *.py
 recursive-include tests *.finished
 recursive-include tests *.running

docs/conf.py

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

docs/openapi.json

@@ -0,0 +1,180 @@
+{
+  "definitions": {},
+  "info": {
+    "description": "Submit and manage workflows",
+    "title": "REANA Workflow Controller",
+    "version": "0.1"
+  },
+  "parameters": {},
+  "paths": {
+    "/api/workflows": {
+      "get": {
+        "description": "This resource is expecting an organization name and an user UUID. The information related to all workflows for a given user will be served as JSON",
+        "operationId": "get_workflows",
+        "parameters": [
+          {
+            "description": "Required. Organization which the worklow belongs to.",
+            "in": "query",
+            "name": "organization",
+            "required": true,
+            "type": "string"
+          },
+          {
+            "description": "Required. UUID of workflow owner.",
+            "in": "query",
+            "name": "user",
+            "required": true,
+            "type": "string"
+          }
+        ],
+        "produces": [
+          "application/json"
+        ],
+        "responses": {
+          "200": {
+            "description": "Requests succeeded. The response contains the current workflows for a given user and organization.",
+            "examples": {
+              "application/json": [
+                {
+                  "id": "256b25f4-4cfb-4684-b7a8-73872ef455a1",
+                  "organization": "default_org",
+                  "status": "running",
+                  "user": "00000000-0000-0000-0000-000000000000"
+                },
+                {
+                  "id": "3c9b117c-d40a-49e3-a6de-5f89fcada5a3",
+                  "organization": "default_org",
+                  "status": "finished",
+                  "user": "00000000-0000-0000-0000-000000000000"
+                },
+                {
+                  "id": "72e3ee4f-9cd3-4dc7-906c-24511d9f5ee3",
+                  "organization": "default_org",
+                  "status": "waiting",
+                  "user": "00000000-0000-0000-0000-000000000000"
+                },
+                {
+                  "id": "c4c0a1a6-beef-46c7-be04-bf4b3beca5a1",
+                  "organization": "default_org",
+                  "status": "waiting",
+                  "user": "00000000-0000-0000-0000-000000000000"
+                }
+              ]
+            },
+            "schema": {
+              "items": {
+                "properties": {
+                  "id": {
+                    "type": "string"
+                  },
+                  "organization": {
+                    "type": "string"
+                  },
+                  "status": {
+                    "type": "string"
+                  },
+                  "user": {
+                    "type": "string"
+                  }
+                },
+                "type": "object"
+              },
+              "type": "array"
+            }
+          },
+          "400": {
+            "description": "Request failed. The incoming data specification seems malformed."
+          },
+          "500": {
+            "description": "Request failed. Internal controller error.",
+            "examples": {
+              "application/json": {
+                "message": "Either organization or user doesn't exist."
+              }
+            }
+          }
+        },
+        "summary": "Returns all workflows."
+      }
+    },
+    "/api/yadage": {
+      "post": {
+        "consumes": [
+          "application/json"
+        ],
+        "description": "This resource is expecting JSON data with all the necessary informations to instantiate a yadage workflow.",
+        "operationId": "create_yadage_workflow",
+        "parameters": [
+          {
+            "description": "Required. Organization which the worklow belongs to.",
+            "in": "query",
+            "name": "organization",
+            "required": true,
+            "type": "string"
+          },
+          {
+            "description": "Required. UUID of workflow owner.",
+            "in": "query",
+            "name": "user",
+            "required": true,
+            "type": "string"
+          },
+          {
+            "description": "Specification with necessary data to instantiate a yadage workflow.",
+            "in": "body",
+            "name": "yadage_payload",
+            "required": true,
+            "schema": {
+              "properties": {
+                "nparallel": {
+                  "type": "integer"
+                },
+                "preset_pars": {
+                  "type": "object"
+                },
+                "toplevel": {
+                  "type": "string"
+                },
+                "workflow": {
+                  "type": "string"
+                }
+              },
+              "type": "object"
+            }
+          }
+        ],
+        "produces": [
+          "application/json"
+        ],
+        "responses": {
+          "200": {
+            "description": "Request succeeded. The workflow has been instantiated.",
+            "examples": {
+              "application/json": {
+                "message": "Workflow successfully launched",
+                "workflow_id": "cdcf48b1-c2f3-4693-8230-b066e088c6ac"
+              }
+            },
+            "schema": {
+              "properties": {
+                "message": {
+                  "type": "string"
+                },
+                "workflow_id": {
+                  "type": "string"
+                }
+              },
+              "type": "object"
+            }
+          },
+          "400": {
+            "description": "Request failed. The incoming data specification seems malformed"
+          }
+        },
+        "summary": "Creates a new yadage workflow."
+      }
+    }
+  },
+  "swagger": "2.0",
+  "tags": []
+}

docs/restapi.rst

@@ -1,15 +1,7 @@
 REST API
 ========
 
-GET /api/workflows
-------------------
-
-.. autofunction:: reana_workflow_controller.rest.get_workflows
-
-
-POST /api/yadage
-----------------
-
-.. autofunction:: reana_workflow_controller.rest.yadage_endpoint
-
+The REANA Workflow Controller component offers a REST API for managing
+workflows.
 
+.. openapi:: openapi.json