Merge branch 'osw-updates-merge-status-on-api-actions' into 'master'

Return more consistent values for merge_status on V4 MR APIs

Closes #20639

See merge request gitlab-org/gitlab-ce!16626

changelogs/unreleased/osw-updates-merge-status-on-api-actions.yml

+---
+title: Return more consistent values for merge_status on MR APIs
+merge_request:
+author:
+type: fixed

lib/api/entities.rb

@@ -507,7 +507,16 @@ module API
       expose :work_in_progress?, as: :work_in_progress
       expose :milestone, using: Entities::Milestone
       expose :merge_when_pipeline_succeeds
-      expose :merge_status
+
+      # Ideally we should deprecate `MergeRequest#merge_status` exposure and
+      # use `MergeRequest#mergeable?` instead (boolean).
+      # See https://gitlab.com/gitlab-org/gitlab-ce/issues/42344 for more
+      # information.
+      expose :merge_status do |merge_request|
+        # In order to avoid having a breaking change for users, we keep returning the
+        # expected values from MergeRequest#merge_status state machine.
+        merge_request.mergeable? ? 'can_be_merged' : 'cannot_be_merged'
+      end
       expose :diff_head_sha, as: :sha
       expose :merge_commit_sha
       expose :user_notes_count