From 4f1dc51d9583f491a3b0bf4c1c0177a07e687006 Mon Sep 17 00:00:00 2001
From: Anita Kuno <anteaya@anteaya.info>
Date: Wed, 6 Jul 2016 16:20:50 -0400
Subject: [PATCH] Add example commands for the Tags 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 Tags section of the api documentation.

Change-Id: I437ad1416aa26c9f114498b39d7c707299c7149c
---
 storyboard/api/v1/tags.py | 32 ++++++++++++++++++++++++++++++--
 1 file changed, 30 insertions(+), 2 deletions(-)

diff --git a/storyboard/api/v1/tags.py b/storyboard/api/v1/tags.py
index ea391223..0623621c 100644
--- a/storyboard/api/v1/tags.py
+++ b/storyboard/api/v1/tags.py
@@ -39,6 +39,10 @@ class TagsController(rest.RestController):
     def get_one(self, tag_id):
         """Retrieve details about one tag.
 
+        Example::
+
+          curl https://my.example.org/api/v1/tags/159
+
         :param tag_id: An ID of the tag.
         """
         tag = tags_api.tag_get_by_id(tag_id)
@@ -52,8 +56,11 @@ class TagsController(rest.RestController):
     @wsme_pecan.wsexpose([wmodels.Tag], int, wtypes.text, int, int, int)
     def get_all(self, story_id=None, name=None, marker=None, limit=None,
                 offset=None):
-        """Retrieve all tags for a given Story. If no story_id is provided
-        all tags will be returned, optionally filtered by name.
+        """Retrieve all tags.
+
+        Example::
+
+          curl https://my.example.org/api/v1/tags
 
         :param story_id: Filter tags by story ID.
         :param name: Filter tags by name.
@@ -83,6 +90,13 @@ class TagsController(rest.RestController):
     def put(self, story_id, tags):
         """Add a list of tags to a Story.
 
+        Example::
+
+          curl https://my.example.org/api/v1/tags/19 -X PUT \\
+          -H 'Authorization: Bearer MY_ACCESS_TOKEN' \\
+          -H 'Content-Type: application/json;charset=UTF-8' \\
+          --data-binary '["taga","tagb"]'
+
         :param story_id: An id of a Story to which the tags should be added.
         :param tags: A list of tags to be added.
         """
@@ -111,6 +125,13 @@ class TagsController(rest.RestController):
     def post(self, tag_name):
         """Create a tag not attached to any Story.
 
+        Example::
+
+           curl https://my.example.org/api/v1/tags \\
+           -H 'Authorization: Bearer MY_ACCESS_TOKEN' \\
+           -H 'Content-Type: application/json;charset=UTF-8' \\
+           --data-binary '{"tag_name":"created-via-api"}'
+
         :param tag_name: The name of a new tag.
         """
 
@@ -122,6 +143,13 @@ class TagsController(rest.RestController):
     def delete(self, story_id, tags):
         """Remove a list of tags from a Story.
 
+        Example::
+
+          curl https://my.example.org/api/v1/tags/19 -X DELETE \\
+          -H 'Authorization: Bearer MY_ACCESS_TOKEN' \\
+          -H 'Content-Type: application/json;charset=UTF-8' \\
+          --data-binary '["taga","tagb"]'
+
         :param story_id: An id of a Story from which the tags should be
                          removed.
         :param tags: A list of tags to be removed.