From f9349bead42e92e7926501c54f43a389b19450a8 Mon Sep 17 00:00:00 2001
From: Anita Kuno <anteaya@anteaya.info>
Date: Wed, 22 Jun 2016 13:52:56 -0400
Subject: [PATCH] Add example commands for the Story api

Currently the api documentation does not include example commands.
It would be very friendly for our users to have some example
commands to follow and use the api. This patch adds examples to
the Story section of the api documentation.

Change-Id: Ic0ddb4debfc9c13cf1da39f541541e3e4bb5e05b
---
 storyboard/api/v1/stories.py | 33 ++++++++++++++++++++++++++++++++-
 storyboard/api/v1/tasks.py   | 29 ++++++++++++++++++++++++++++-
 2 files changed, 60 insertions(+), 2 deletions(-)

diff --git a/storyboard/api/v1/stories.py b/storyboard/api/v1/stories.py
index ad670a14..14b0e885 100644
--- a/storyboard/api/v1/stories.py
+++ b/storyboard/api/v1/stories.py
@@ -69,6 +69,10 @@ class StoriesController(rest.RestController):
     def get_one(self, story_id):
         """Retrieve details about one story.
 
+        Example::
+
+          curl https://my.example.org/api/v1/stories/11
+
         :param story_id: An ID of the story.
         """
         story = stories_api.story_get(
@@ -91,6 +95,10 @@ class StoriesController(rest.RestController):
                 sort_field='id', sort_dir='asc'):
         """Retrieve definitions of all of the stories.
 
+        Example::
+
+          curl https://my.example.org/api/v1/stories
+
         :param title: A string to filter the title by.
         :param description: A string to filter the description by.
         :param status: Only show stories with this particular status.
@@ -165,6 +173,13 @@ class StoriesController(rest.RestController):
     def post(self, story):
         """Create a new story.
 
+        Example::
+
+          curl 'https://my.example.org/api/v1/stories' \\
+          -H 'Authorization: Bearer MY_ACCESS_TOKEN' \\
+          -H 'Content-Type: application/json;charset=UTF-8' \\
+          --data-binary '{"title":"Test Story","description":"A test story."}'
+
         :param story: A story within the request body.
         """
 
@@ -212,6 +227,13 @@ class StoriesController(rest.RestController):
     def put(self, story_id, story):
         """Modify this story.
 
+        Example::
+
+          curl 'https://my.example.org/api/v1/stories/19' -X PUT \\
+          -H 'Authorization: Bearer MY_ACCESS_TOKEN' \\
+          -H 'Content-Type: application/json;charset=UTF-8' \\
+          --data-binary '{"title":"Modified","description":"New description."}'
+
         :param story_id: An ID of the story.
         :param story: A story within the request body.
         """
@@ -276,7 +298,12 @@ class StoriesController(rest.RestController):
     @secure(checks.superuser)
     @wsme_pecan.wsexpose(wmodels.Story, int, status_code=204)
     def delete(self, story_id):
-        """Delete this story.
+        """Delete this story. This command is only available to Admin users.
+
+        Example::
+
+          curl 'https://my.example.org/api/v1/stories/5' -X DELETE \\
+          -H 'Authorization: Bearer MY_ACCESS_TOKEN'
 
         :param story_id: An ID of the story.
         """
@@ -295,6 +322,10 @@ class StoriesController(rest.RestController):
     def search(self, q="", marker=None, offset=None, limit=None):
         """The search endpoint for stories.
 
+        Example::
+
+          curl https://my.example.org/api/v1/stories/search?q=pep8
+
         :param q: The query string.
         :return: List of Stories matching the query.
         """
diff --git a/storyboard/api/v1/tasks.py b/storyboard/api/v1/tasks.py
index 76cefb0c..837f3170 100644
--- a/storyboard/api/v1/tasks.py
+++ b/storyboard/api/v1/tasks.py
@@ -447,6 +447,10 @@ class TasksNestedController(rest.RestController):
     def get_one(self, story_id, task_id):
         """Retrieve details about one task.
 
+        Example::
+
+          curl https://my.example.org/api/v1/stories/11/tasks/2691
+
         :param story_id: An ID of the story.
         :param task_id: An ID of the task.
         """
@@ -469,7 +473,11 @@ class TasksNestedController(rest.RestController):
                 project_group_id=None, branch_id=None, milestone_id=None,
                 status=None, priority=None, marker=None, limit=None,
                 sort_field='id', sort_dir='asc', link=None):
-        """Retrieve definitions of all of the tasks.
+        """Retrieve definitions of all of the tasks associated with a story.
+
+        Example::
+
+          curl https://my.example.org/api/v1/stories/11/tasks
 
         :param story_id: filter tasks by story ID.
         :param title: search by task title.
@@ -537,6 +545,13 @@ class TasksNestedController(rest.RestController):
     def post(self, story_id, task):
         """Create a new task.
 
+        Example::
+
+          curl 'https://my.example.org/api/v1/stories/19/tasks' \\
+          -H 'Authorization: Bearer MY_ACCESS_TOKEN' \\
+          -H 'Content-Type: application/json;charset=UTF-8' \\
+          --data-binary '{"title":"Task Foo","project_id":153,"key":"todo"}'
+
         :param story_id: An ID of the story.
         :param task: a task within the request body.
         """
@@ -572,6 +587,13 @@ class TasksNestedController(rest.RestController):
     def put(self, story_id, task_id, task):
         """Modify this task.
 
+        Example::
+
+          curl 'https://my.example.org/api/v1/stories/19/tasks/19' -X PUT \\
+          -H 'Authorization: Bearer MY_ACCESS_TOKEN' \\
+          -H 'Content-Type: application/json;charset=UTF-8' \\
+          --data-binary '{"title":"Task Foio","project_id":153,"key":"todo"}'
+
         :param story_id: An ID of the story.
         :param task_id: An ID of the task.
         :param task: a task within the request body.
@@ -600,6 +622,11 @@ class TasksNestedController(rest.RestController):
     def delete(self, story_id, task_id):
         """Delete this task.
 
+        Example::
+
+          curl 'https://my.example.org/api/v1/stories/11/tasks/28' -X DELETE \\
+          -H 'Authorization: Bearer MY_ACCESS_TOKEN'
+
         :param story_id: An ID of the story.
         :param task_id: An ID of the task.
         """