Merge "Add example commands for the Story api"

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.
         """

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.
         """