API documentation update for milestones
Updated the milestones API documentation and added return codes descriptions.
This commit is contained in:
parent
33c1463645
commit
4a60c377b8
3 changed files with 48 additions and 25 deletions
|
@ -1,6 +1,6 @@
|
||||||
## List project milestones
|
## List project milestones
|
||||||
|
|
||||||
Get a list of project milestones.
|
Returns a list of project milestones.
|
||||||
|
|
||||||
```
|
```
|
||||||
GET /projects/:id/milestones
|
GET /projects/:id/milestones
|
||||||
|
@ -10,9 +10,16 @@ Parameters:
|
||||||
|
|
||||||
+ `id` (required) - The ID of a project
|
+ `id` (required) - The ID of a project
|
||||||
|
|
||||||
## Single milestone
|
Return values:
|
||||||
|
|
||||||
Get a single project milestone.
|
+ `200 Ok` on success and the list of project milestones
|
||||||
|
+ `401 Unauthorized` if user is not authenticated
|
||||||
|
+ `404 Not Found` if project ID not found
|
||||||
|
|
||||||
|
|
||||||
|
## Get single milestone
|
||||||
|
|
||||||
|
Gets a single project milestone.
|
||||||
|
|
||||||
```
|
```
|
||||||
GET /projects/:id/milestones/:milestone_id
|
GET /projects/:id/milestones/:milestone_id
|
||||||
|
@ -23,9 +30,16 @@ Parameters:
|
||||||
+ `id` (required) - The ID of a project
|
+ `id` (required) - The ID of a project
|
||||||
+ `milestone_id` (required) - The ID of a project milestone
|
+ `milestone_id` (required) - The ID of a project milestone
|
||||||
|
|
||||||
## New milestone
|
Return values:
|
||||||
|
|
||||||
Create a new project milestone.
|
+ `200 Ok` on success and the single milestone
|
||||||
|
+ `401 Unauthorized` if user is not authenticated
|
||||||
|
+ `404 Not Found` if project ID not found
|
||||||
|
|
||||||
|
|
||||||
|
## Create new milestone
|
||||||
|
|
||||||
|
Creates a new project milestone.
|
||||||
|
|
||||||
```
|
```
|
||||||
POST /projects/:id/milestones
|
POST /projects/:id/milestones
|
||||||
|
@ -38,9 +52,17 @@ Parameters:
|
||||||
+ `description` (optional) - The description of the milestone
|
+ `description` (optional) - The description of the milestone
|
||||||
+ `due_date` (optional) - The due date of the milestone
|
+ `due_date` (optional) - The due date of the milestone
|
||||||
|
|
||||||
|
Return values:
|
||||||
|
|
||||||
|
+ `201 Created` on success and the new milestone
|
||||||
|
+ `400 Bad Request` if the required attribute title is not given
|
||||||
|
+ `401 Unauthorized` if user is not authenticated
|
||||||
|
+ `404 Not Found` if project ID not found
|
||||||
|
|
||||||
|
|
||||||
## Edit milestone
|
## Edit milestone
|
||||||
|
|
||||||
Update an existing project milestone.
|
Updates an existing project milestone.
|
||||||
|
|
||||||
```
|
```
|
||||||
PUT /projects/:id/milestones/:milestone_id
|
PUT /projects/:id/milestones/:milestone_id
|
||||||
|
@ -54,3 +76,9 @@ Parameters:
|
||||||
+ `description` (optional) - The description of a milestone
|
+ `description` (optional) - The description of a milestone
|
||||||
+ `due_date` (optional) - The due date of the milestone
|
+ `due_date` (optional) - The due date of the milestone
|
||||||
+ `closed` (optional) - The status of the milestone
|
+ `closed` (optional) - The status of the milestone
|
||||||
|
|
||||||
|
Return values:
|
||||||
|
|
||||||
|
+ `200 Ok` on success and the updated milestone
|
||||||
|
+ `401 Unauthorized` if user is not authenticated
|
||||||
|
+ `404 Not Found` if project ID or milestone ID not found
|
||||||
|
|
|
@ -4,20 +4,6 @@ module Gitlab
|
||||||
before { authenticate! }
|
before { authenticate! }
|
||||||
|
|
||||||
resource :projects do
|
resource :projects do
|
||||||
|
|
||||||
helpers do
|
|
||||||
# If an error occurs this helper method handles error codes for a given milestone
|
|
||||||
#
|
|
||||||
# Parameters:
|
|
||||||
# milestone_errors (required) - The erros collection of a milestone
|
|
||||||
#
|
|
||||||
def handle_milestone_errors(milestone_errors)
|
|
||||||
if milestone_errors[:title].any?
|
|
||||||
bad_request!(:title)
|
|
||||||
end
|
|
||||||
end
|
|
||||||
end
|
|
||||||
|
|
||||||
# Get a list of project milestones
|
# Get a list of project milestones
|
||||||
#
|
#
|
||||||
# Parameters:
|
# Parameters:
|
||||||
|
@ -56,12 +42,13 @@ module Gitlab
|
||||||
post ":id/milestones" do
|
post ":id/milestones" do
|
||||||
authorize! :admin_milestone, user_project
|
authorize! :admin_milestone, user_project
|
||||||
|
|
||||||
|
bad_request!(:title) unless params[:title].present?
|
||||||
|
|
||||||
attrs = attributes_for_keys [:title, :description, :due_date]
|
attrs = attributes_for_keys [:title, :description, :due_date]
|
||||||
@milestone = user_project.milestones.new attrs
|
@milestone = user_project.milestones.new attrs
|
||||||
if @milestone.save
|
if @milestone.save
|
||||||
present @milestone, with: Entities::Milestone
|
present @milestone, with: Entities::Milestone
|
||||||
else
|
else
|
||||||
handle_milestone_errors(@milestone.errors)
|
|
||||||
not_found!
|
not_found!
|
||||||
end
|
end
|
||||||
end
|
end
|
||||||
|
@ -85,7 +72,6 @@ module Gitlab
|
||||||
if @milestone.update_attributes attrs
|
if @milestone.update_attributes attrs
|
||||||
present @milestone, with: Entities::Milestone
|
present @milestone, with: Entities::Milestone
|
||||||
else
|
else
|
||||||
handle_milestone_errors(@milestone.errors)
|
|
||||||
not_found!
|
not_found!
|
||||||
end
|
end
|
||||||
end
|
end
|
||||||
|
|
|
@ -16,6 +16,11 @@ describe Gitlab::API do
|
||||||
json_response.should be_an Array
|
json_response.should be_an Array
|
||||||
json_response.first['title'].should == milestone.title
|
json_response.first['title'].should == milestone.title
|
||||||
end
|
end
|
||||||
|
|
||||||
|
it "should return a 401 error if user not authenticated" do
|
||||||
|
get api("/projects/#{project.id}/milestones")
|
||||||
|
response.status.should == 401
|
||||||
|
end
|
||||||
end
|
end
|
||||||
|
|
||||||
describe "GET /projects/:id/milestones/:milestone_id" do
|
describe "GET /projects/:id/milestones/:milestone_id" do
|
||||||
|
@ -25,6 +30,11 @@ describe Gitlab::API do
|
||||||
json_response['title'].should == milestone.title
|
json_response['title'].should == milestone.title
|
||||||
end
|
end
|
||||||
|
|
||||||
|
it "should return 401 error if user not authenticated" do
|
||||||
|
get api("/projects/#{project.id}/milestones/#{milestone.id}")
|
||||||
|
response.status.should == 401
|
||||||
|
end
|
||||||
|
|
||||||
it "should return a 404 error if milestone id not found" do
|
it "should return a 404 error if milestone id not found" do
|
||||||
get api("/projects/#{project.id}/milestones/1234", user)
|
get api("/projects/#{project.id}/milestones/1234", user)
|
||||||
response.status.should == 404
|
response.status.should == 404
|
||||||
|
@ -33,8 +43,7 @@ describe Gitlab::API do
|
||||||
|
|
||||||
describe "POST /projects/:id/milestones" do
|
describe "POST /projects/:id/milestones" do
|
||||||
it "should create a new project milestone" do
|
it "should create a new project milestone" do
|
||||||
post api("/projects/#{project.id}/milestones", user),
|
post api("/projects/#{project.id}/milestones", user), title: 'new milestone'
|
||||||
title: 'new milestone'
|
|
||||||
response.status.should == 201
|
response.status.should == 201
|
||||||
json_response['title'].should == 'new milestone'
|
json_response['title'].should == 'new milestone'
|
||||||
json_response['description'].should be_nil
|
json_response['description'].should be_nil
|
||||||
|
@ -62,7 +71,7 @@ describe Gitlab::API do
|
||||||
json_response['title'].should == 'updated title'
|
json_response['title'].should == 'updated title'
|
||||||
end
|
end
|
||||||
|
|
||||||
it "should return a 404 error if milestone is not found" do
|
it "should return a 404 error if milestone id not found" do
|
||||||
put api("/projects/#{project.id}/milestones/1234", user),
|
put api("/projects/#{project.id}/milestones/1234", user),
|
||||||
title: 'updated title'
|
title: 'updated title'
|
||||||
response.status.should == 404
|
response.status.should == 404
|
||||||
|
|
Loading…
Reference in a new issue