From 5ff08a68c940c161280129d92e6d5286d7de3dbe Mon Sep 17 00:00:00 2001 From: Paul Millette Date: Mon, 28 Nov 2016 11:10:24 -0500 Subject: [PATCH] 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 | 93 ++++++++++++++++++- .../input/attach_volume-body.json | 4 + .../input/create_instance-body.json | 10 ++ .../input/create_volume-body.json | 9 ++ .../input/create_volume_type-body.json | 4 + .../input/delete_instance-body.json | 3 + .../input/delete_volume-body.json | 3 + .../input/detach_volume-body.json | 4 + .../input/rebuild_instance-body.json | 7 ++ .../input/resize_instance-body.json | 4 + .../input/resize_volume-body.json | 4 + .../input/update_instance_entity-body.json | 4 + doc/api_examples/output/entities.json | 30 ++++++ doc/api_examples/output/entity.json | 18 ++++ doc/api_examples/output/info.json | 9 ++ doc/api_examples/output/instances.json | 18 ++++ .../output/update_instance_entity.json | 16 ++++ doc/api_examples/output/volume_type.json | 4 + doc/api_examples/output/volume_types.json | 10 ++ doc/api_examples/output/volumes.json | 26 ++++++ 20 files changed, 278 insertions(+), 2 deletions(-) create mode 100644 doc/api_examples/input/attach_volume-body.json create mode 100644 doc/api_examples/input/create_instance-body.json create mode 100644 doc/api_examples/input/create_volume-body.json create mode 100644 doc/api_examples/input/create_volume_type-body.json create mode 100644 doc/api_examples/input/delete_instance-body.json create mode 100644 doc/api_examples/input/delete_volume-body.json create mode 100644 doc/api_examples/input/detach_volume-body.json create mode 100644 doc/api_examples/input/rebuild_instance-body.json create mode 100644 doc/api_examples/input/resize_instance-body.json create mode 100644 doc/api_examples/input/resize_volume-body.json create mode 100644 doc/api_examples/input/update_instance_entity-body.json create mode 100644 doc/api_examples/output/entities.json create mode 100644 doc/api_examples/output/entity.json create mode 100755 doc/api_examples/output/info.json create mode 100644 doc/api_examples/output/instances.json create mode 100644 doc/api_examples/output/update_instance_entity.json create mode 100644 doc/api_examples/output/volume_type.json create mode 100644 doc/api_examples/output/volume_types.json create mode 100644 doc/api_examples/output/volumes.json diff --git a/almanach/api/v1/routes.py b/almanach/api/v1/routes.py index 163ffb0..2bdab66 100644 --- a/almanach/api/v1/routes.py +++ b/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) diff --git a/doc/api_examples/input/attach_volume-body.json b/doc/api_examples/input/attach_volume-body.json new file mode 100644 index 0000000..07c6eae --- /dev/null +++ b/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"] +} \ No newline at end of file diff --git a/doc/api_examples/input/create_instance-body.json b/doc/api_examples/input/create_instance-body.json new file mode 100644 index 0000000..11375cb --- /dev/null +++ b/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" +} \ No newline at end of file diff --git a/doc/api_examples/input/create_volume-body.json b/doc/api_examples/input/create_volume-body.json new file mode 100644 index 0000000..1556f9c --- /dev/null +++ b/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": "" +} \ No newline at end of file diff --git a/doc/api_examples/input/create_volume_type-body.json b/doc/api_examples/input/create_volume_type-body.json new file mode 100644 index 0000000..96cdb06 --- /dev/null +++ b/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" +} \ No newline at end of file diff --git a/doc/api_examples/input/delete_instance-body.json b/doc/api_examples/input/delete_instance-body.json new file mode 100644 index 0000000..d8b8bee --- /dev/null +++ b/doc/api_examples/input/delete_instance-body.json @@ -0,0 +1,3 @@ +{ + "date": "2016-11-24 17:55:05+00:00" +} \ No newline at end of file diff --git a/doc/api_examples/input/delete_volume-body.json b/doc/api_examples/input/delete_volume-body.json new file mode 100644 index 0000000..d8b8bee --- /dev/null +++ b/doc/api_examples/input/delete_volume-body.json @@ -0,0 +1,3 @@ +{ + "date": "2016-11-24 17:55:05+00:00" +} \ No newline at end of file diff --git a/doc/api_examples/input/detach_volume-body.json b/doc/api_examples/input/detach_volume-body.json new file mode 100644 index 0000000..36a20e4 --- /dev/null +++ b/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"] +} \ No newline at end of file diff --git a/doc/api_examples/input/rebuild_instance-body.json b/doc/api_examples/input/rebuild_instance-body.json new file mode 100644 index 0000000..f4fdf13 --- /dev/null +++ b/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" +} \ No newline at end of file diff --git a/doc/api_examples/input/resize_instance-body.json b/doc/api_examples/input/resize_instance-body.json new file mode 100644 index 0000000..a24fefa --- /dev/null +++ b/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" +} \ No newline at end of file diff --git a/doc/api_examples/input/resize_volume-body.json b/doc/api_examples/input/resize_volume-body.json new file mode 100644 index 0000000..4e11a36 --- /dev/null +++ b/doc/api_examples/input/resize_volume-body.json @@ -0,0 +1,4 @@ +{ + "size": 22, + "date": "2016-11-24 17:25:05+00:00" +} \ No newline at end of file diff --git a/doc/api_examples/input/update_instance_entity-body.json b/doc/api_examples/input/update_instance_entity-body.json new file mode 100644 index 0000000..4ea34d1 --- /dev/null +++ b/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" +} \ No newline at end of file diff --git a/doc/api_examples/output/entities.json b/doc/api_examples/output/entities.json new file mode 100644 index 0000000..718de81 --- /dev/null +++ b/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 + } +] \ No newline at end of file diff --git a/doc/api_examples/output/entity.json b/doc/api_examples/output/entity.json new file mode 100644 index 0000000..fb79f23 --- /dev/null +++ b/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": {} + } +] \ No newline at end of file diff --git a/doc/api_examples/output/info.json b/doc/api_examples/output/info.json new file mode 100755 index 0000000..5b24bd9 --- /dev/null +++ b/doc/api_examples/output/info.json @@ -0,0 +1,9 @@ +{ + "info": { + "version": "3.2.0" + }, + "database": { + "all_entities": 999, + "active_entities": 997 + } +} \ No newline at end of file diff --git a/doc/api_examples/output/instances.json b/doc/api_examples/output/instances.json new file mode 100644 index 0000000..b8bf263 --- /dev/null +++ b/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": {} + } +] diff --git a/doc/api_examples/output/update_instance_entity.json b/doc/api_examples/output/update_instance_entity.json new file mode 100644 index 0000000..afe891e --- /dev/null +++ b/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": {} +} \ No newline at end of file diff --git a/doc/api_examples/output/volume_type.json b/doc/api_examples/output/volume_type.json new file mode 100644 index 0000000..8296ca5 --- /dev/null +++ b/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" +} \ No newline at end of file diff --git a/doc/api_examples/output/volume_types.json b/doc/api_examples/output/volume_types.json new file mode 100644 index 0000000..f2d4fd6 --- /dev/null +++ b/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" + } +] \ No newline at end of file diff --git a/doc/api_examples/output/volumes.json b/doc/api_examples/output/volumes.json new file mode 100644 index 0000000..1446463 --- /dev/null +++ b/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 + } +] \ No newline at end of file