Resolve "Return how many commits the source branch is behind the target branch through the API"

changelogs/unreleased/36534-show-commit-behind-mr-api.yml

+---
+title: Adds diverged_commits_count field to GET api/v4/projects/:project_id/merge_requests/:merge_request_iid
+merge_request: 21405
+author: Jacopo Beschi @jacopo-beschi
+type: added

doc/api/merge_requests.md

@@ -352,6 +352,7 @@ Parameters:
 - `id` (required) - The ID or [URL-encoded path of the project](README.md#namespaced-path-encoding) owned by the authenticated user
 - `merge_request_iid` (required) - The internal ID of the merge request
 - `render_html` (optional) - If `true` response includes rendered HTML for title and description
+- `include_diverged_commits_count` (optional) - If `true` response includes the commits behind the target branch
 
 ```json
 {
@@ -435,7 +436,8 @@ Parameters:
     "username" : "root",
     "id" : 1,
     "name" : "Administrator"
-  }
+  },
+  "diverged_commits_count": 2
 }
 ```
 

lib/api/entities.rb

@@ -687,6 +687,8 @@ module API
 
       expose :diff_refs, using: Entities::DiffRefs
 
+      expose :diverged_commits_count, as: :diverged_commits_count, if: -> (_, options) { options[:include_diverged_commits_count] }
+
       def build_available?(options)
         options[:project]&.feature_available?(:builds, options[:current_user])
       end

lib/api/merge_requests.rb

@@ -233,6 +233,7 @@ module API
       params do
         requires :merge_request_iid, type: Integer, desc: 'The IID of a merge request'
         optional :render_html, type: Boolean, desc: 'Returns the description and title rendered HTML'
+        optional :include_diverged_commits_count, type: Boolean, desc: 'Returns the commits count behind the target branch'
       end
       desc 'Get a single merge request' do
         success Entities::MergeRequest
@@ -240,7 +241,7 @@ module API
       get ':id/merge_requests/:merge_request_iid' do
         merge_request = find_merge_request_with_access(params[:merge_request_iid])
 
-        present merge_request, with: Entities::MergeRequest, current_user: current_user, project: user_project, render_html: params[:render_html]
+        present merge_request, with: Entities::MergeRequest, current_user: current_user, project: user_project, render_html: params[:render_html], include_diverged_commits_count: params[:include_diverged_commits_count]
       end
 
       desc 'Get the participants of a merge request' do

spec/requests/api/merge_requests_spec.rb

@@ -353,6 +353,15 @@ describe API::MergeRequests do
       end
     end
 
+    it 'returns the commits behind the target branch when include_diverged_commits_count is present' do
+      allow_any_instance_of(merge_request.class).to receive(:diverged_commits_count).and_return(1)
+
+      get api("/projects/#{project.id}/merge_requests/#{merge_request.iid}", user), include_diverged_commits_count: true
+
+      expect(response).to have_gitlab_http_status(200)
+      expect(json_response['diverged_commits_count']).to eq(1)
+    end
+
     it "returns a 404 error if merge_request_iid not found" do
       get api("/projects/#{project.id}/merge_requests/999", user)
       expect(response).to have_gitlab_http_status(404)