Add json outputs to documentation

- use literal includes to show input and output
- add input payloads folder to docs
- add output payloads folder to docs

Change-Id: Ifaa782422edc2d0fee70fcc2f8909fd928e363cc

almanach/api/v1/routes.py

@@ -87,6 +87,11 @@ def get_info():
     """Display information about the current version and counts of entities in the database.
 
     :code 200 OK: Service is available
+
+    Example output:
+
+    .. literalinclude:: ../api_examples/output/info.json
+        :language: json
     """
     return controller.get_application_info()
 
@@ -109,6 +114,11 @@ def create_instance(project_id):
     :code 201 Created: Instance successfully created
     :code 400 Bad Request: If request data has an invalid or missing field
     :code 404 Not Found: If tenant does not exist
+
+    Example input:
+
+    .. literalinclude:: ../api_examples/input/create_instance-body.json
+        :language: json
     """
     instance = jsonutils.loads(flask.request.data)
     LOG.info("Creating instance for tenant %s with data %s", project_id, instance)
@@ -139,6 +149,11 @@ def delete_instance(instance_id):
     :code 202 Accepted: Instance successfully deleted
     :code 400 Bad Request: If request data has an invalid or missing field
     :code 404 Not Found: If instance does not exist
+
+    Example input:
+
+    .. literalinclude:: ../api_examples/input/delete_instance-body.json
+        :language: json
     """
     data = jsonutils.loads(flask.request.data)
     LOG.info("Deleting instance with id %s with data %s", instance_id, data)
@@ -163,6 +178,11 @@ def resize_instance(instance_id):
     :code 200 OK:  Instance successfully re-sized
     :code 400 Bad Request: If request data has an invalid or missing field
     :code 404 Not Found: If instance does not exist
+
+    Example input:
+
+    .. literalinclude:: ../api_examples/input/resize_instance-body.json
+        :language: json
     """
     instance = jsonutils.loads(flask.request.data)
     LOG.info("Resizing instance with id %s with data %s", instance_id, instance)
@@ -190,6 +210,11 @@ def rebuild_instance(instance_id):
     :code 200 OK:  Instance successfully rebuilt
     :code 400 Bad Request: If request data has an invalid or missing field
     :code 404 Not Found: If instance does not exist
+
+    Example input:
+
+    .. literalinclude:: ../api_examples/input/rebuild_instance-body.json
+        :language: json
     """
     instance = jsonutils.loads(flask.request.data)
     LOG.info("Rebuilding instance with id %s with data %s", instance_id, instance)
@@ -217,6 +242,11 @@ def list_instances(project_id):
     :code 200 OK: instance list exists
     :code 400 Bad Request: If request data has an invalid or missing field
     :code 404 Not Found: If tenant does not exist.
+
+    Example output:
+
+    .. literalinclude:: ../api_examples/output/instances.json
+        :language: json
     """
     start, end = get_period()
     LOG.info("Listing instances between %s and %s", start, end)
@@ -240,6 +270,11 @@ def create_volume(project_id):
     :code 201 Created:  Volume successfully created
     :code 400 Bad Request: If request data has an invalid or missing field
     :code 404 Not Found: If tenant does not exist.
+
+    Example input:
+
+    .. literalinclude:: ../api_examples/input/create_volume-body.json
+        :language: json
     """
     volume = jsonutils.loads(flask.request.data)
     LOG.info("Creating volume for tenant %s with data %s", project_id, volume)
@@ -292,6 +327,11 @@ def resize_volume(volume_id):
     :code 200 OK: Volume successfully re-sized
     :code 400 Bad Request: If request data has an invalid or missing field
     :code 404 Not Found: If volume does not exist.
+
+    Example input:
+
+    .. literalinclude:: ../api_examples/input/resize_volume-body.json
+        :language: json
     """
     volume = jsonutils.loads(flask.request.data)
     LOG.info("Resizing volume with id %s with data %s", volume_id, volume)
@@ -317,6 +357,11 @@ def attach_volume(volume_id):
     :code 200 OK: Volume successfully attached
     :code 400 Bad Request: If request data has an invalid or missing field
     :code 404 Not Found: If volume does not exist.
+
+    Example input:
+
+    .. literalinclude:: ../api_examples/input/attach_volume-body.json
+        :language: json
     """
     volume = jsonutils.loads(flask.request.data)
     LOG.info("Attaching volume with id %s with data %s", volume_id, volume)
@@ -336,12 +381,15 @@ def detach_volume(volume_id):
     """Detaches a volume when the volume is detached in OpenStack.
 
     :arg uuid volume_id: Volume Uuid
-    :arg datetime date: Y-m-d H:M:S.f
-    :arg dict attachments: The volume attachments
 
     :code 200 OK: Volume successfully detached
     :code 400 Bad Request: If request data has an invalid or missing field
     :code 404 Not Found: If volume does not exist.
+
+    Example input:
+
+    .. literalinclude:: ../api_examples/input/detach_volume-body.json
+        :language: json
     """
     volume = jsonutils.loads(flask.request.data)
     LOG.info("Detaching volume with id %s with data %s", volume_id, volume)
@@ -367,6 +415,11 @@ def list_volumes(project_id):
     :code 200 OK: volume list exists
     :code 400 Bad Request: If request data has an invalid or missing field
     :code 404 Not Found: If tenant does not exist.
+
+    Example output:
+
+    .. literalinclude:: ../api_examples/output/volumes.json
+        :language: json
     """
     start, end = get_period()
     LOG.info("Listing volumes between %s and %s", start, end)
@@ -386,6 +439,12 @@ def list_entity(project_id):
     :code 200 OK: instances and volumes list exists
     :code 400 Bad Request: If request data has an invalid or missing field
     :code 404 Not Found: If tenant does not exist.
+
+
+    Example output:
+
+    .. literalinclude:: ../api_examples/output/entities.json
+        :language: json
     """
     start, end = get_period()
     LOG.info("Listing entities between %s and %s", start, end)
@@ -405,6 +464,16 @@ def update_instance_entity(instance_id):
     :code 200 OK: Entity successfully updated
     :code 400 Bad Request: If request data has an invalid or missing field
     :code 404 Not Found: If instance does not exist.
+
+    Example input:
+
+    .. literalinclude:: ../api_examples/input/update_instance_entity-body.json
+        :language: json
+
+    Example output:
+
+    .. literalinclude:: ../api_examples/output/update_instance_entity.json
+        :language: json
     """
     data = jsonutils.loads(flask.request.data)
     LOG.info("Updating instance entity with id %s with data %s", instance_id, data)
@@ -443,6 +512,11 @@ def get_entity(entity_id):
 
     :code 200 OK: Entity exists
     :code 404 Not Found: If the entity does not exist
+
+    Example output:
+
+    .. literalinclude:: ../api_examples/output/entity.json
+        :language: json
     """
     return controller.get_all_entities_by_id(entity_id)
 
@@ -454,6 +528,11 @@ def list_volume_types():
     """List volume types.
 
     :code 200 OK: Volume types exist
+
+    Example output:
+
+    .. literalinclude:: ../api_examples/output/volume_types.json
+        :language: json
     """
     LOG.info("Listing volumes types")
     return controller.list_volume_types()
@@ -470,6 +549,11 @@ def get_volume_type(type_id):
     :code 200 OK: Volume type exists
     :code 400 Bad Request: If request data has an invalid or missing field
     :code 404 Not Found: If the volume type does not exist
+
+    Example output:
+
+    .. literalinclude:: ../api_examples/output/volume_type.json
+        :language: json
     """
     LOG.info("Get volumes type for id %s", type_id)
     return controller.get_volume_type(type_id)
@@ -486,6 +570,11 @@ def create_volume_type():
 
     :code 201 Created: Volume successfully created
     :code 400 Bad Request: If request data has an invalid or missing field
+
+    Example input:
+
+    .. literalinclude:: ../api_examples/input/create_volume_type-body.json
+        :language: json
     """
     volume_type = jsonutils.loads(flask.request.data)
     LOG.info("Creating volume type with data '%s'", volume_type)

doc/api_examples/input/attach_volume-body.json

@@ -0,0 +1,4 @@
+{
+  "date": "2016-11-24 17:15:05+00:00",
+  "attachments": ["460bb2b6-28d6-42c0-9da4-4288dc3025cc"]
+}

doc/api_examples/input/create_instance-body.json

@@ -0,0 +1,10 @@
+{
+  "project_id": "ce2d9f6bde52447a831887aac8b7ec98",
+  "id": "460bb2b6-28d6-42c0-9da4-4288dc3025cc",
+  "created_at": "2016-11-24 15:15:05+00:00",
+  "flavor": "my_flavor_name",
+  "os_type": "linux",
+  "os_version": "7",
+  "os_distro": "centos",
+  "name": "created_instance1"
+}

doc/api_examples/input/create_volume-body.json

@@ -0,0 +1,9 @@
+{
+  "project_id": "ce2d9f6bde52447a831887aac8b7ec98",
+  "volume_id": "a1c95ee7-3317-4597-b176-131209368d27",
+  "start": "2016-11-24 17:15:05+00:00",
+  "volume_type": "8b2944c2-9268-4fca-a5df-b4f23a7af1ba",
+  "size": 20,
+  "volume_name": "created_volume2",
+  "attached_to": ""
+}

doc/api_examples/input/create_volume_type-body.json

@@ -0,0 +1,4 @@
+{
+  "type_id": "ae23091d-caf5-44f9-ae7d-2be3623c5e3a",
+  "type_name": "my_volume_type3"
+}

doc/api_examples/input/delete_instance-body.json

@@ -0,0 +1,3 @@
+{
+  "date": "2016-11-24 17:55:05+00:00"
+}

doc/api_examples/input/delete_volume-body.json

@@ -0,0 +1,3 @@
+{
+  "date": "2016-11-24 17:55:05+00:00"
+}

doc/api_examples/input/detach_volume-body.json

@@ -0,0 +1,4 @@
+{
+  "date": "2016-11-24 17:25:05+00:00",
+  "attachments": ["460bb2b6-28d6-42c0-9da4-4288dc3025cc"]
+}

doc/api_examples/input/rebuild_instance-body.json

@@ -0,0 +1,7 @@
+{
+  "instance_id": "37870255-a0f0-447c-b602-7e29f32cc88c",
+  "rebuild_date": "2016-11-24 15:15:05+00:00",
+  "os_type": "linux",
+  "version": "14.04",
+  "distro": "ubuntu"
+}

doc/api_examples/input/resize_instance-body.json

@@ -0,0 +1,4 @@
+{
+  "flavor": "my_new_flavor",
+  "date": "2016-11-24 17:25:05+00:00"
+}

doc/api_examples/input/resize_volume-body.json

@@ -0,0 +1,4 @@
+{
+  "size": 22,
+  "date": "2016-11-24 17:25:05+00:00"
+}

doc/api_examples/input/update_instance_entity-body.json

@@ -0,0 +1,4 @@
+{
+  "start_date": "2016-11-24T17:25:05.00Z",
+  "end_date": "2016-11-24T17:35:05.00Z"
+}

doc/api_examples/output/entities.json

@@ -0,0 +1,30 @@
+[
+  {
+    "entity_id": "b5a4b119-7444-4993-afda-89b8f8f70147",
+    "end": null,
+    "name": "my.host.name.com",
+    "last_event": "2016-11-24 21:15:35+00:00",
+    "entity_type": "instance",
+    "start": "2016-11-24 21:15:35+00:00",
+    "flavor": "my_flavor_name",
+    "project_id": "ce2d9f6bde52447a831887aac8b7ec98",
+    "os": {
+      "os_type": "linux",
+      "version": "7",
+      "distro": "centos"
+    },
+    "metadata": {}
+  },
+  {
+    "entity_id": "020f3636-6a8a-4a37-beb0-0735074175a9",
+    "attached_to": ["b5a4b119-7444-4993-afda-89b8f8f70147"],
+    "end": null,
+    "name": "my.host.name.com-volume",
+    "last_event": "2016-11-24 21:16:47.106000+00:00",
+    "entity_type": "volume",
+    "volume_type": "my_volume_type1",
+    "start": "2016-11-24 21:16:47.106000+00:00",
+    "project_id": "ce2d9f6bde52447a831887aac8b7ec98",
+    "size": 20
+  }
+]

doc/api_examples/output/entity.json

@@ -0,0 +1,18 @@
+[
+  {
+    "entity_id": "7f8284db-c955-4383-b253-d54cbc8c4364",
+    "end": null,
+    "name": "host1.ccom",
+    "last_event": "2016-11-24 15:14:08+00:00",
+    "entity_type": "instance",
+    "start": "2016-11-24 15:14:08+00:00",
+    "flavor": "my_flavor_name",
+    "project_id": "ce2d9f6bde52447a831887aac8b7ec98",
+    "os": {
+      "os_type": "linux",
+      "version": "7",
+      "distro": "centos"
+    },
+    "metadata": {}
+  }
+]

doc/api_examples/output/info.json

@@ -0,0 +1,9 @@
+{
+  "info": {
+    "version": "3.2.0"
+  },
+  "database": {
+    "all_entities": 999,
+    "active_entities": 997
+  }
+}

doc/api_examples/output/instances.json

@@ -0,0 +1,18 @@
+[
+  {
+    "entity_id": "7f8284db-c955-4383-b253-d54cbc8c4364",
+    "end": null,
+    "name": "host1.com",
+    "last_event": "2016-11-24 15:14:08+00:00",
+    "entity_type": "instance",
+    "start": "2016-11-24 15:14:08+00:00",
+    "flavor": "my_flavor_name",
+    "project_id": "ce2d9f6bde52447a831887aac8b7ec98",
+    "os": {
+      "os_type": "linux",
+      "version": "7",
+      "distro": "centos"
+    },
+    "metadata": {}
+  }
+]

doc/api_examples/output/update_instance_entity.json

@@ -0,0 +1,16 @@
+{
+  "entity_id": "460bb2b6-28d6-42c0-9da4-4288dc3025cc",
+  "end": "2016-11-24 17:35:05+00:00",
+  "name": "my_instance_name",
+  "last_event": "2016-11-24 17:25:05+00:00",
+  "entity_type": "instance",
+  "start": "2016-11-24 17:25:05+00:00",
+  "flavor": "my_flavor_name",
+  "project_id": "ce2d9f6bde52447a831887aac8b7ec98",
+  "os": {
+    "os_type": "linux",
+    "version": "7",
+    "distro": "centos"
+  },
+  "metadata": {}
+}

doc/api_examples/output/volume_type.json

@@ -0,0 +1,4 @@
+{
+  "volume_type_id": "8b2944c2-9268-4fca-a5df-b4f23a7af1ba",
+  "volume_type_name": "my_volume_type1"
+}

doc/api_examples/output/volume_types.json

@@ -0,0 +1,10 @@
+[
+  {
+    "volume_type_id": "8b2944c2-9268-4fca-a5df-b4f23a7af1ba",
+    "volume_type_name": "my_volume_type1"
+  },
+  {
+    "volume_type_id": "a1c73195-d54e-4aea-8c3e-3df017b7a44a",
+    "volume_type_name": "my_volume_type2"
+  }
+]

doc/api_examples/output/volumes.json

@@ -0,0 +1,26 @@
+[
+  {
+    "entity_id": "020f3636-6a8a-4a37-beb0-0735074175a9",
+    "attached_to": ["b5a4b119-7444-4993-afda-89b8f8f70147"],
+    "end": null,
+    "name": "my.host.name.com-volume",
+    "last_event": "2016-11-24 21:16:47.106000+00:00",
+    "entity_type": "volume",
+    "volume_type": "my_volume_type",
+    "start": "2016-11-24 21:16:47.106000+00:00",
+    "project_id": "ce2d9f6bde52447a831887aac8b7ec98",
+    "size": 20
+  },
+  {
+    "entity_id": "020f3636-6a8a-4a37-beb0-0735074175a9",
+    "attached_to": [],
+    "end": "2016-11-24 21:16:47.106000+00:00",
+    "name": "",
+    "last_event": "2016-11-24 21:16:47.106000+00:00",
+    "entity_type": "volume",
+    "volume_type": "my_volume_type2",
+    "start": "2016-11-24 21:15:38+00:00",
+    "project_id": "ce2d9f6bde52447a831887aac8b7ec98",
+    "size": 20
+  }
+]