opendev/storyboard
Code Issues Proposed changes

Fix docs

Browse Source 
Fixed some mistakes in docs, added new
controllers to docs.

Change-Id: I35fd12fc1262ba6671d154fbb760220968a29578
This commit is contained in:
Aleksey Ripinen
2015-03-23 15:49:51 +03:00
parent b60310bedf
commit 247236681f
15 changed files with 162 additions and 87 deletions
Download Patch File Download Diff File Expand all files Collapse all files

38
doc/source/webapi/v1.rst
View File

@@ -37,16 +37,54 @@ Tasks
.. rest-controller:: storyboard.api.v1.tasks:TasksController
:webprefix: /v1/tasks
Branches
========
.. rest-controller:: storyboard.api.v1.branches:BranchesController
:webprefix: /v1/branches
Milestones
==========
.. rest-controller:: storyboard.api.v1.milestones:MilestonesController
:webprefix: /v1/milestones
Tags
====
.. rest-controller:: storyboard.api.v1.tags:TagsController
:webprefix: /v1/tags
Subscriptions
=============
.. rest-controller:: storyboard.api.v1.subscriptions:SubscriptionsController
:webprefix: /v1/subscriptions
Users
=====
.. rest-controller:: storyboard.api.v1.users:UsersController
:webprefix: /v1/users
Teams
=====
.. rest-controller:: storyboard.api.v1.teams:TeamsController
:webprefix: /v1/teams
.. rest-controller:: storyboard.api.v1.teams:UsersSubcontroller
:webprefix: /v1/teams/<team_id>/users
User Preferences
================
.. rest-controller:: storyboard.api.v1.user_preferences:UserPreferencesController
:webprefix: /v1/users/<user_id>/preferences
System Info
===========
.. rest-controller:: storyboard.api.v1.system_info:SystemInfoController
:webprefix: /v1/systeminfo
User Tokens
===========
.. rest-controller:: storyboard.api.v1.user_tokens:UserTokensController
:webprefix: /v1/users/<user_id>/tokens
############
Object model
############

8
storyboard/api/v1/branches.py
View File

@@ -52,7 +52,7 @@ class BranchesController(rest.RestController):
def get_one(self, branch_id):
"""Retrieve information about the given branch.
:param branch_id: branch ID.
:param branch_id: Branch ID.
"""
branch = branches_api.branch_get(branch_id)
@@ -76,7 +76,7 @@ class BranchesController(rest.RestController):
:param project_id: Filter branches based on project.
:param project_group_id: Filter branches based on project group.
:param sort_field: The name of the field to sort on.
:param sort_dir: sort direction for results (asc, desc).
:param sort_dir: Sort direction for results (asc, desc).
"""
# Boundary check on limit.
if limit is None:
@@ -113,7 +113,7 @@ class BranchesController(rest.RestController):
def post(self, branch):
"""Create a new branch.
:param branch: a branch within the request body.
:param branch: A branch within the request body.
"""
branch_dict = branch.as_dict()
@@ -132,7 +132,7 @@ class BranchesController(rest.RestController):
"""Modify this branch.
:param branch_id: An ID of the branch.
:param branch: a branch within the request body.
:param branch: A branch within the request body.
"""
branch_dict = branch.as_dict(omit_unset=True)

8
storyboard/api/v1/milestones.py
View File

@@ -53,7 +53,7 @@ class MilestonesController(rest.RestController):
def get_one(self, milestone_id):
"""Retrieve information about the given milestone.
:param milestone_id: milestone ID.
:param milestone_id: Milestone ID.
"""
milestones = milestones_api.milestone_get(milestone_id)
@@ -76,7 +76,7 @@ class MilestonesController(rest.RestController):
:param name: Filter milestones based on name.
:param branch_id: Filter milestones based on branch_id.
:param sort_field: The name of the field to sort on.
:param sort_dir: sort direction for results (asc, desc).
:param sort_dir: Sort direction for results (asc, desc).
"""
# Boundary check on limit.
if limit is None:
@@ -112,7 +112,7 @@ class MilestonesController(rest.RestController):
def post(self, milestone):
"""Create a new milestone.
:param milestone: a milestone within the request body.
:param milestone: A milestone within the request body.
"""
# we can't create expired milestones
@@ -129,7 +129,7 @@ class MilestonesController(rest.RestController):
"""Modify this milestone.
:param milestone_id: An ID of the milestone.
:param milestone: a milestone within the request body.
:param milestone: A milestone within the request body.
"""
milestone_dict = milestone.as_dict(omit_unset=True)

31
storyboard/api/v1/project_groups.py
View File

@@ -46,7 +46,7 @@ class ProjectsSubcontroller(rest.RestController):
def get(self, project_group_id):
"""Get projects inside a project group.
:param project_group_id: An ID of the project group
:param project_group_id: An ID of the project group.
"""
project_group = project_groups.project_group_get(project_group_id)
@@ -62,7 +62,10 @@ class ProjectsSubcontroller(rest.RestController):
@secure(checks.superuser)
@wsme_pecan.wsexpose(wmodels.Project, int, int)
def put(self, project_group_id, project_id):
"""Add a project to a project_group
"""Add a project to a project_group.
:param project_group_id: An ID of the project group.
:param project_id: An ID of project in this project group.
"""
project_groups.project_group_add_project(project_group_id, project_id)
@@ -73,8 +76,12 @@ class ProjectsSubcontroller(rest.RestController):
@secure(checks.superuser)
@wsme_pecan.wsexpose(None, int, int, status_code=204)
def delete(self, project_group_id, project_id):
"""Delete a project from a project_group
"""Delete a project from a project_group.
:param project_group_id: An ID of the project group.
:param project_id: An ID of project in this project group.
"""
project_groups.project_group_delete_project(project_group_id,
project_id)
@@ -84,7 +91,7 @@ class ProjectGroupsController(rest.RestController):
NOTE: PUT requests should be used to update only top-level fields.
The nested fields (projects) should be updated using requests to a
/projects subcontroller
projects subcontroller.
"""
validation_post_schema = validations.PROJECT_GROUPS_POST_SCHEMA
@@ -96,7 +103,7 @@ class ProjectGroupsController(rest.RestController):
def get_one(self, project_group_id):
"""Retrieve information about the given project group.
:param project_group_id: project group id.
:param project_group_id: Project group id.
"""
group = project_groups.project_group_get(project_group_id)
@@ -112,7 +119,15 @@ class ProjectGroupsController(rest.RestController):
wtypes.text, wtypes.text, wtypes.text)
def get(self, marker=None, limit=None, name=None, title=None,
sort_field='id', sort_dir='asc'):
"""Retrieve a list of projects groups."""
"""Retrieve a list of projects groups.
:param marker: The resource id where the page should begin.
:param limit: The number of project groups to retrieve.
:param name: A string to filter the name by.
:param title: A string to filter the title by.
:param sort_field: The name of the field to sort on.
:param sort_dir: Sort direction for results (asc, desc).
"""
if limit is None:
limit = CONF.page_size_default
@@ -145,7 +160,7 @@ class ProjectGroupsController(rest.RestController):
def post(self, project_group):
"""Create a new project group.
:param project_group: a project group within the request body.
:param project_group: A project group within the request body.
"""
created_group = project_groups.project_group_create(
@@ -160,7 +175,7 @@ class ProjectGroupsController(rest.RestController):
"""Modify this project group.
:param project_group_id: An ID of the project group.
:param project_group: a project group within the request body.
:param project_group: A project group within the request body.
"""
updated_group = project_groups.project_group_update(

13
storyboard/api/v1/projects.py
View File

@@ -53,7 +53,7 @@ class ProjectsController(rest.RestController):
def get_one_by_id(self, project_id):
"""Retrieve information about the given project.
:param project_id: project ID.
:param project_id: Project ID.
"""
project = projects_api.project_get(project_id)
@@ -69,7 +69,7 @@ class ProjectsController(rest.RestController):
def get_one_by_name(self, project_name):
"""Retrieve information about the given project.
:param name: project name.
:param name: Project name.
"""
project = projects_api.project_get_by_name(project_name)
@@ -92,10 +92,11 @@ class ProjectsController(rest.RestController):
:param name: A string to filter the name by.
:param description: A string to filter the description by.
:param project_group_id: The ID of a project group to which the
projects must belong.
projects must belong.
:param sort_field: The name of the field to sort on.
:param sort_dir: sort direction for results (asc, desc).
:param sort_dir: Sort direction for results (asc, desc).
"""
# Boundary check on limit.
if limit is None:
limit = CONF.page_size_default
@@ -131,7 +132,7 @@ class ProjectsController(rest.RestController):
def post(self, project):
"""Create a new project.
:param project: a project within the request body.
:param project: A project within the request body.
"""
result = projects_api.project_create(project.as_dict())
@@ -144,7 +145,7 @@ class ProjectsController(rest.RestController):
"""Modify this project.
:param project_id: An ID of the project.
:param project: a project within the request body.
:param project: A project within the request body.
"""
result = projects_api.project_update(project_id,
project.as_dict(omit_unset=True))

16
storyboard/api/v1/stories.py
View File

@@ -79,15 +79,15 @@ class StoriesController(rest.RestController):
: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.
:param assignee_id: filter stories by who they are assigned to.
:param project_group_id: filter stories by project group.
:param project_id: filter stories by project ID.
:param tags: a list of tags to filter by.
:param assignee_id: Filter stories by who they are assigned to.
:param project_group_id: Filter stories by project group.
:param project_id: Filter stories by project ID.
:param tags: A list of tags to filter by.
:param marker: The resource id where the page should begin.
:param limit: The number of stories to retrieve.
:param tags_filter_type: type of tags filter.
:param tags_filter_type: Type of tags filter.
:param sort_field: The name of the field to sort on.
:param sort_dir: sort direction for results (asc, desc).
:param sort_dir: Sort direction for results (asc, desc).
"""
# Boundary check on limit.
@@ -134,7 +134,7 @@ class StoriesController(rest.RestController):
def post(self, story):
"""Create a new story.
:param story: a story within the request body.
:param story: A story within the request body.
"""
story_dict = story.as_dict()
@@ -161,7 +161,7 @@ class StoriesController(rest.RestController):
"""Modify this story.
:param story_id: An ID of the story.
:param story: a story within the request body.
:param story: A story within the request body.
"""
original_story = stories_api.story_get_simple(story_id)

4
storyboard/api/v1/subscription_events.py
View File

@@ -102,7 +102,7 @@ class SubscriptionEventsController(rest.RestController):
:param event_type: The type of resource to search by.
:param subscriber_id: The unique ID of the subscriber to search by.
:param sort_field: The name of the field to sort on.
:param sort_dir: sort direction for results (asc, desc).
:param sort_dir: Sort direction for results (asc, desc).
"""
# Boundary check on limit.
@@ -147,7 +147,7 @@ class SubscriptionEventsController(rest.RestController):
"""Delete a specific subscription.
:param subscription_event_id: The unique id of the
subscription_event to delete.
subscription_event to delete.
"""
subscription_event = subscription_events_api \
.subscription_events_get(subscription_event_id)

2
storyboard/api/v1/subscriptions.py
View File

@@ -95,7 +95,7 @@ class SubscriptionsController(rest.RestController):
:param target_id: The unique ID of the resource to search by.
:param user_id: The unique ID of the user to search by.
:param sort_field: The name of the field to sort on.
:param sort_dir: sort direction for results (asc, desc).
:param sort_dir: Sort direction for results (asc, desc).
"""
# Boundary check on limit.

15
storyboard/api/v1/tags.py
View File

@@ -52,7 +52,7 @@ class TagsController(rest.RestController):
"""Retrieve all tags for a given Story. If no story_id is provided
all tags will be returned.
:param story_id: filter tags by story ID.
:param story_id: Filter tags by story ID.
"""
if not story_id:
@@ -72,8 +72,8 @@ class TagsController(rest.RestController):
def put(self, story_id, tags):
"""Add a list of tags to a Story.
:param story_id: an id of a Story to which the tags should be added.
:param tags: a list of tags to be added
:param story_id: An id of a Story to which the tags should be added.
:param tags: A list of tags to be added.
"""
story = stories_api.story_get(story_id)
@@ -91,8 +91,7 @@ class TagsController(rest.RestController):
def post(self, tag_name):
"""Create a tag not attached to any Story.
:param tag_name: The name of a new tag
:return: the tag
:param tag_name: The name of a new tag.
"""
tag = tags_api.tag_create({"name": tag_name})
@@ -103,9 +102,9 @@ class TagsController(rest.RestController):
def delete(self, story_id, tags):
"""Remove a list of tags from a Story.
:param story_id: an id of a Story from which the tags should be
removed.
:param tags: a list of tags to be removed
:param story_id: An id of a Story from which the tags should be
removed.
:param tags: A list of tags to be removed.
"""
story = stories_api.story_get(story_id)

24
storyboard/api/v1/tasks.py
View File

@@ -72,19 +72,19 @@ class TasksController(rest.RestController):
limit=None, sort_field='id', sort_dir='asc'):
"""Retrieve definitions of all of the tasks.
:param title: search by task title.
:param story_id: filter tasks by story ID.
:param assignee_id: filter tasks by who they are assigned to.
:param project_id: filter the tasks based on project.
:param project_group_id: filter tasks based on project group.
:param branch_id: filter tasks based on branch_id.
:param milestone_id: filter tasks based on milestone.
:param status: filter tasks by status.
:param priority: filter tasks by priority.
:param title: Search by task title.
:param story_id: Filter tasks by story ID.
:param assignee_id: Filter tasks by who they are assigned to.
:param project_id: Filter the tasks based on project.
:param project_group_id: Filter tasks based on project group.
:param branch_id: Filter tasks based on branch_id.
:param milestone_id: Filter tasks based on milestone.
:param status: Filter tasks by status.
:param priority: Filter tasks by priority.
:param marker: The resource id where the page should begin.
:param limit: The number of tasks to retrieve.
:param sort_field: The name of the field to sort on.
:param sort_dir: sort direction for results (asc, desc).
:param sort_dir: Sort direction for results (asc, desc).
"""
# Boundary check on limit.
@@ -144,7 +144,7 @@ class TasksController(rest.RestController):
def post(self, task):
"""Create a new task.
:param task: a task within the request body.
:param task: A task within the request body.
"""
if task.creator_id and task.creator_id != request.current_user_id:
@@ -176,7 +176,7 @@ class TasksController(rest.RestController):
"""Modify this task.
:param task_id: An ID of the task.
:param task: a task within the request body.
:param task: A task within the request body.
"""
original_task = tasks_api.task_get(task_id)

22
storyboard/api/v1/teams.py
View File

@@ -43,7 +43,7 @@ class UsersSubcontroller(rest.RestController):
def get(self, team_id):
"""Get users inside a team.
:param team_id: An ID of the team
:param team_id: An ID of the team.
"""
team = teams_api.team_get(team_id)
@@ -57,7 +57,11 @@ class UsersSubcontroller(rest.RestController):
@secure(checks.superuser)
@wsme_pecan.wsexpose(wmodels.User, int, int)
def put(self, team_id, user_id):
"""Add a user to a team."""
"""Add a user to a team.
:param team_id: An ID of the team.
:param user_id: An ID of the user.
"""
teams_api.team_add_user(team_id, user_id)
user = users_api.user_get(user_id)
@@ -68,7 +72,11 @@ class UsersSubcontroller(rest.RestController):
@secure(checks.superuser)
@wsme_pecan.wsexpose(None, int, int, status_code=204)
def delete(self, team_id, user_id):
"""Delete a user from a team."""
"""Delete a user from a team.
:param: team_id: An ID of the team.
:param: user_id: An ID of the user.
"""
teams_api.team_delete_user(team_id, user_id)
@@ -84,7 +92,7 @@ class TeamsController(rest.RestController):
def get_one_by_id(self, team_id):
"""Retrieve information about the given team.
:param team_id: team ID.
:param team_id: Team ID.
"""
team = teams_api.team_get(team_id)
@@ -100,7 +108,7 @@ class TeamsController(rest.RestController):
def get_one_by_name(self, team_name):
"""Retrieve information about the given team.
:param team_name: team name.
:param team_name: Team name.
"""
team = teams_api.team_get_by_name(team_name)
@@ -123,7 +131,7 @@ class TeamsController(rest.RestController):
:param name: A string to filter the name by.
:param description: A string to filter the description by.
:param sort_field: The name of the field to sort on.
:param sort_dir: sort direction for results (asc, desc).
:param sort_dir: Sort direction for results (asc, desc).
"""
# Boundary check on limit.
if limit is None:
@@ -169,7 +177,7 @@ class TeamsController(rest.RestController):
"""Modify this team.
:param team_id: An ID of the team.
:param team: a team within the request body.
:param team: A team within the request body.
"""
result = teams_api.team_update(team_id,
team.as_dict(omit_unset=True))

34
storyboard/api/v1/timeline.py
View File

@@ -47,10 +47,12 @@ class TimeLineEventsController(rest.RestController):
"""Retrieve details about one event.
:param story_id: An ID of the story. It stays in params as a
placeholder so that pecan knows where to match an incoming value.
It will stay unused, as far as events have their own unique ids.
placeholder so that pecan knows where to match an
incoming value. It will stay unused, as far as events
have their own unique ids.
:param event_id: An ID of the event.
"""
event = events_api.event_get(event_id)
if event:
@@ -68,12 +70,12 @@ class TimeLineEventsController(rest.RestController):
limit=None, sort_field=None, sort_dir=None):
"""Retrieve all events that have happened under specified story.
:param story_id: filter events by story ID.
:param story_id: Filter events by story ID.
:param event_type: A selection of event types to get.
:param marker: The resource id where the page should begin.
:param limit: The number of events to retrieve.
:param sort_field: The name of the field to sort on.
:param sort_dir: sort direction for results (asc, desc).
:param sort_dir: Sort direction for results (asc, desc).
"""
# Boundary check on limit.
@@ -122,10 +124,12 @@ class CommentsController(rest.RestController):
"""Retrieve details about one comment.
:param story_id: An ID of the story. It stays in params as a
placeholder so that pecan knows where to match an incoming value.
It will stay unused, as far as comments have their own unique ids.
placeholder so that pecan knows where to match an
incoming value. It will stay unused, as far as
comments have their own unique ids.
:param comment_id: An ID of the comment.
"""
comment = comments_api.comment_get(comment_id)
if comment:
@@ -141,11 +145,11 @@ class CommentsController(rest.RestController):
sort_dir='asc'):
"""Retrieve all comments posted under specified story.
:param story_id: filter comments by story ID.
:param story_id: Filter comments by story ID.
:param marker: The resource id where the page should begin.
:param limit: The number of comments to retrieve.
:param sort_field: The name of the field to sort on.
:param sort_dir: sort direction for results (asc, desc).
:param sort_dir: Sort direction for results (asc, desc).
"""
# Boundary check on limit.
@@ -190,7 +194,7 @@ class CommentsController(rest.RestController):
def post(self, story_id, comment):
"""Create a new comment.
:param story_id: an id of a Story to add a Comment to.
:param story_id: An id of a Story to add a Comment to.
:param comment: The comment itself.
"""
@@ -213,10 +217,11 @@ class CommentsController(rest.RestController):
def put(self, story_id, comment_id, comment_body):
"""Update an existing comment.
:param story_id: a placeholder
:param comment_id: the id of a Comment to be updated
:param comment_body: an updated Comment
:param story_id: A placeholder.
:param comment_id: The id of a Comment to be updated.
:param comment_body: An updated Comment.
"""
comments_api.comment_get(comment_id)
comment_author_id = events_api.events_get_all(
comment_id=comment_id)[0].author_id
@@ -236,9 +241,10 @@ class CommentsController(rest.RestController):
def delete(self, story_id, comment_id):
"""Update an existing comment.
:param story_id: a placeholder
:param comment_id: the id of a Comment to be updated
:param story_id: A placeholder.
:param comment_id: The id of a Comment to be updated.
"""
comment = comments_api.comment_get(comment_id)
if request.current_user_id != comment.author_id:

8
storyboard/api/v1/user_preferences.py
View File

@@ -41,7 +41,10 @@ class UserPreferencesController(rest.RestController):
@wsme_pecan.wsexpose(wtypes.DictType(wtypes.text, wtypes.text), int)
def get_all(self, user_id):
"""Return all preferences for the current user.
:param user_id: An ID of the user.
"""
if request.current_user_id != user_id:
abort(403, _("You can't read preferences of other users."))
return
@@ -56,9 +59,10 @@ class UserPreferencesController(rest.RestController):
"""Allow a user to update their preferences. Note that a user must
explicitly set a preference value to Null/None to have it deleted.
:param user_id The ID of the user whose preferences we're updating.
:param body A dictionary of preference values.
:param user_id: The ID of the user whose preferences we're updating.
:param body: A dictionary of preference values.
"""
if request.current_user_id != user_id:
abort(403, _("You can't change preferences of other users."))

12
storyboard/api/v1/user_tokens.py
View File

@@ -57,7 +57,8 @@ class UserTokensController(rest.RestController):
wtypes.text)
def get_all(self, user_id, marker=None, limit=None, sort_field='id',
sort_dir='asc'):
"""Returns all the access tokens for the provided user.
"""Returns all the access tokens with matching refresh tokens for
the provided user.
:param user_id: The ID of the user.
:param marker: The marker record at which to start the page.
@@ -97,7 +98,8 @@ class UserTokensController(rest.RestController):
@secure(checks.authenticated)
@wsme_pecan.wsexpose(wmodels.AccessToken, int, int)
def get(self, user_id, access_token_id):
"""Returns a specific access token for the given user.
"""Returns a specific access token with assigned refresh token for the
given user.
:param user_id: The ID of the user.
:param access_token_id: The ID of the access token.
@@ -115,7 +117,8 @@ class UserTokensController(rest.RestController):
@secure(checks.authenticated)
@wsme_pecan.wsexpose(wmodels.AccessToken, int, body=wmodels.AccessToken)
def post(self, user_id, body):
"""Create a new access token for the given user.
"""Create a new access token with assigned refresh token for the given
user.
:param user_id: The user ID of the user.
:param body: The access token.
@@ -185,7 +188,8 @@ class UserTokensController(rest.RestController):
@secure(checks.authenticated)
@wsme_pecan.wsexpose(wmodels.AccessToken, int, int, status_code=204)
def delete(self, user_id, access_token_id):
"""Deletes an access token for the given user.
"""Deletes an access token with assigned refresh token for the given
user.
:param user_id: The user ID of the user.
:param access_token_id: The ID of the access token.

14
storyboard/api/v1/users.py
View File

@@ -64,11 +64,11 @@ class UsersController(rest.RestController):
"""Page and filter the users in storyboard.
:param marker: The resource id where the page should begin.
:param limit The number of users to retrieve.
:param username A string of characters to filter the username with.
:param full_name A string of characters to filter the full_name with.
:param limit: The number of users to retrieve.
:param username: A string of characters to filter the username with.
:param full_name: A string of characters to filter the full_name with.
:param sort_field: The name of the field to sort on.
:param sort_dir: sort direction for results (asc, desc).
:param sort_dir: Sort direction for results (asc, desc).
"""
# Boundary check on limit.
@@ -119,7 +119,7 @@ class UsersController(rest.RestController):
def post(self, user):
"""Create a new user.
:param user: a user within the request body.
:param user: A user within the request body.
"""
created_user = users_api.user_create(user.as_dict())
@@ -131,8 +131,8 @@ class UsersController(rest.RestController):
def put(self, user_id, user):
"""Modify this user.
:param user_id: unique id to identify the user.
:param user: a user within the request body.
:param user_id: Unique id to identify the user.
:param user: A user within the request body.
"""
current_user = users_api.user_get(request.current_user_id)