diff --git a/doc/api/merge_requests.md b/doc/api/merge_requests.md new file mode 100644 index 00000000..2f7c93eb --- /dev/null +++ b/doc/api/merge_requests.md @@ -0,0 +1,194 @@ +## List merge requests + +Get all MR for this project. + +``` +GET /:id/merge_requests +``` + +Parameters: + ++ `id` (required) - The ID or code name of a project + +```json +[ + { + "id":1, + "target_branch":"master", + "source_branch":"test1", + "project_id":3, + "title":"test1", + "closed":true, + "merged":false, + "author":{ + "id":1, + "email":"admin@local.host", + "name":"Administrator", + "blocked":false, + "created_at":"2012-04-29T08:46:00Z" + }, + "assignee":{ + "id":1, + "email":"admin@local.host", + "name":"Administrator", + "blocked":false, + "created_at":"2012-04-29T08:46:00Z" + } + } +] +``` + +## Show MR + +Show information about MR. + +``` +GET /:id/merge_request/:merge_request_id +``` + +Parameters: + ++ `id` (required) - The ID or code name of a project ++ `merge_request_id` (required) - The ID of MR + +```json +{ + "id":1, + "target_branch":"master", + "source_branch":"test1", + "project_id":3, + "title":"test1", + "closed":true, + "merged":false, + "author":{ + "id":1, + "email":"admin@local.host", + "name":"Administrator", + "blocked":false, + "created_at":"2012-04-29T08:46:00Z" + }, + "assignee":{ + "id":1, + "email":"admin@local.host", + "name":"Administrator", + "blocked":false, + "created_at":"2012-04-29T08:46:00Z" + } +} +``` + + +## Create MR + +Create MR. + +``` +POST /:id/merge_requests +``` + +Parameters: + ++ `id` (required) - The ID or code name of a project ++ `source_branch` (required) - The source branch ++ `target_branch` (required) - The target branch ++ `assignee_id` - Assignee user ID ++ `title` (required) - Title of MR + +```json +{ + "id":1, + "target_branch":"master", + "source_branch":"test1", + "project_id":3, + "title":"test1", + "closed":true, + "merged":false, + "author":{ + "id":1, + "email":"admin@local.host", + "name":"Administrator", + "blocked":false, + "created_at":"2012-04-29T08:46:00Z" + }, + "assignee":{ + "id":1, + "email":"admin@local.host", + "name":"Administrator", + "blocked":false, + "created_at":"2012-04-29T08:46:00Z" + } +} +``` + +## Update MR + +Update MR. You can change branches, title, or even close the MR. + +``` +PUT /:id/merge_request/:merge_request_id +``` + +Parameters: + ++ `id` (required) - The ID or code name of a project ++ `merge_request_id` (required) - ID of MR ++ `source_branch` - The source branch ++ `target_branch` - The target branch ++ `assignee_id` - Assignee user ID ++ `title` - Title of MR ++ `closed` - Status of MR. true - closed + + +```json +{ + "id":1, + "target_branch":"master", + "source_branch":"test1", + "project_id":3, + "title":"test1", + "closed":true, + "merged":false, + "author":{ + "id":1, + "email":"admin@local.host", + "name":"Administrator", + "blocked":false, + "created_at":"2012-04-29T08:46:00Z" + }, + "assignee":{ + "id":1, + "email":"admin@local.host", + "name":"Administrator", + "blocked":false, + "created_at":"2012-04-29T08:46:00Z" + } +} +``` +## Post comment to MR + +Post comment to MR + +``` +POST /:id/merge_request/:merge_request_id/comments +``` + +Parameters: + ++ `id` (required) - The ID or code name of a project ++ `merge_request_id` (required) - ID of MR ++ `note` (required) - Text of comment + +Will return created note with status `201 Created` on success, or `404 Not found` on fail. + +```json +{ + "author":{ + "id":1, + "email":"admin@local.host", + "name":"Administrator", + "blocked":false, + "created_at":"2012-04-29T08:46:00Z" + }, + "note":"text1" +} +``` diff --git a/lib/api/merge_requests.rb b/lib/api/merge_requests.rb index e701339b..c9377ad2 100644 --- a/lib/api/merge_requests.rb +++ b/lib/api/merge_requests.rb @@ -4,14 +4,30 @@ module Gitlab before { authenticate! } resource :projects do - #list + + # List merge requests + # + # Parameters: + # id (required) - The ID or code name of a project + # + # Example: + # GET /:id/merge_requests + # get ":id/merge_requests" do authorize! :read_merge_request, user_project - present user_project.merge_requests, with: Entities::MergeRequest + present paginate(user_project.merge_requests), with: Entities::MergeRequest end - #show + # Show MR + # + # Parameters: + # id (required) - The ID or code name of a project + # merge_request_id (required) - The ID of MR + # + # Example: + # GET /:id/merge_request/:merge_request_id + # get ":id/merge_request/:merge_request_id" do merge_request = user_project.merge_requests.find(params[:merge_request_id]) @@ -20,7 +36,19 @@ module Gitlab present merge_request, with: Entities::MergeRequest end - #create merge_request + # Create MR + # + # Parameters: + # + # id (required) - The ID or code name of a project + # source_branch (required) - The source branch + # target_branch (required) - The target branch + # assignee_id - Assignee user ID + # title (required) - Title of MR + # + # Example: + # POST /:id/merge_requests + # post ":id/merge_requests" do attrs = attributes_for_keys [:source_branch, :target_branch, :assignee_id, :title] merge_request = user_project.merge_requests.new(attrs) @@ -36,7 +64,19 @@ module Gitlab end end - #update merge_request + # Update MR + # + # Parameters: + # id (required) - The ID or code name of a project + # merge_request_id (required) - ID of MR + # source_branch - The source branch + # target_branch - The target branch + # assignee_id - Assignee user ID + # title - Title of MR + # closed - Status of MR. true - closed + # Example: + # PUT /:id/merge_request/:merge_request_id + # put ":id/merge_request/:merge_request_id" do attrs = attributes_for_keys [:source_branch, :target_branch, :assignee_id, :title, :closed] merge_request = user_project.merge_requests.find(params[:merge_request_id]) @@ -52,7 +92,15 @@ module Gitlab end end - #post comment to merge request + # Post comment to merge request + # + # Parameters: + # id (required) - The ID or code name of a project + # merge_request_id (required) - ID of MR + # note (required) - Text of comment + # Examples: + # POST /:id/merge_request/:merge_request_id/comments + # post ":id/merge_request/:merge_request_id/comments" do merge_request = user_project.merge_requests.find(params[:merge_request_id]) note = merge_request.notes.new(note: params[:note], project_id: user_project.id)