Add include_parent_milestones to milestones API

- Add optional param include_parent_milestones to
project milestones API with default value false
- Modify GET request to include parent groups
milestones if include_parent_milestones is true
- Add specs for project milestones API
- Update API documentation

changelogs/unreleased/196066-add-milestone-expired-info-be-2.yml

+---
+title: Add include_parent_milestones param to milestones API
+merge_request: 36944
+author:
+type: added

doc/api/milestones.md

@@ -25,13 +25,14 @@ GET /projects/:id/milestones?search=version
 
 Parameters:
 
-| Attribute | Type   | Required | Description |
-| --------- | ------ | -------- | ----------- |
-| `id`      | integer/string | yes | The ID or [URL-encoded path of the project](README.md#namespaced-path-encoding) owned by the authenticated user |
-| `iids[]`  | integer array | optional | Return only the milestones having the given `iid` |
-| `state`   | string | optional | Return only `active` or `closed` milestones |
-| `title`   | string | optional | Return only the milestones having the given `title` |
-| `search`  | string | optional | Return only milestones with a title or description matching the provided string |
+| Attribute                    | Type   | Required | Description |
+| ---------------------------- | ------ | -------- | ----------- |
+| `id`                         | integer/string | yes | The ID or [URL-encoded path of the project](README.md#namespaced-path-encoding) owned by the authenticated user |
+| `iids[]`                     | integer array | optional | Return only the milestones having the given `iid` |
+| `state`                      | string | optional | Return only `active` or `closed` milestones |
+| `title`                      | string | optional | Return only the milestones having the given `title` |
+| `search`                     | string | optional | Return only milestones with a title or description matching the provided string |
+| `include_parent_milestones`  | boolean | optional | Include milestones from parent group and descendants |
 
 ```shell
 curl --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/projects/5/milestones"

lib/api/milestone_responses.rb

@@ -31,12 +31,14 @@ module API
         end
 
         def list_milestones_for(parent)
-          milestones = parent.milestones.order_id_desc
-          milestones = Milestone.filter_by_state(milestones, params[:state])
-          milestones = filter_by_iid(milestones, params[:iids]) if params[:iids].present?
-          milestones = filter_by_title(milestones, params[:title]) if params[:title]
+          finder_params = params.merge(milestones_finder_params(parent))
+          milestones = MilestonesFinder.new(finder_params).execute
           milestones = filter_by_search(milestones, params[:search]) if params[:search]
 
+          if params[:iids].present? && !params[:include_parent_milestones]
+            milestones = filter_by_iid(milestones, params[:iids])
+          end
+
           present paginate(milestones), with: Entities::Milestone
         end
 
@@ -96,6 +98,34 @@ module API
             [MergeRequestsFinder, Entities::MergeRequestBasic]
           end
         end
+
+        def milestones_finder_params(parent)
+          finder_params = {}
+
+          if parent.is_a?(Group)
+            finder_params[:group_ids] = parent.id
+          else
+            finder_params[:project_ids] = parent.id
+            finder_params[:group_ids] = parent_group_ids(parent)
+          end
+
+          finder_params
+        end
+
+        def parent_group_ids(parent)
+          return unless params[:include_parent_milestones].present?
+          return unless can_read_parent_group?(parent)
+
+          parent.group.self_and_descendants
+            .public_or_visible_to_user(current_user)
+            .select(:id)
+        end
+
+        def can_read_parent_group?(parent)
+          return unless parent&.group&.present?
+
+          Ability.allowed?(current_user, :read_group, parent.group)
+        end
       end
     end
   end

lib/api/project_milestones.rb

@@ -16,6 +16,8 @@ module API
       end
       params do
         use :list_params
+        optional :include_parent_milestones, type: Boolean, default: false,
+                  desc: 'Include milestones from parent group and descendants'
       end
       get ":id/milestones" do
         authorize! :read_milestone, user_project

spec/requests/api/project_milestones_spec.rb

@@ -16,6 +16,58 @@ RSpec.describe API::ProjectMilestones do
     let(:route) { "/projects/#{project.id}/milestones" }
   end
 
+  describe 'GET /projects/:id/milestones' do
+    context 'when include_parent_milestones is true' do
+      let(:group) { create(:group, :public) }
+      let(:project) { create(:project, group: group) }
+      let!(:group_milestone) { create(:milestone, group: group) }
+
+      context 'when user has access to group parent' do
+        let(:nested_group) { create(:group, :public, parent: group) }
+        let!(:nested_group_milestone) { create(:milestone, group: nested_group) }
+
+        it 'result includes parent group and subgroup milestones' do
+          milestones = [nested_group_milestone, group_milestone, milestone, closed_milestone]
+
+          get api("/projects/#{project.id}/milestones", user),
+              params: { include_parent_milestones: true }
+
+          expect(response).to have_gitlab_http_status(:ok)
+          expect(json_response.size).to eq(4)
+
+          expect(json_response.map { |entry| entry["id"] }).to eq(milestones.map(&:id))
+        end
+      end
+
+      context 'when user has no access to group parent' do
+        it 'does not show parent group milestones' do
+          allow(Ability).to receive(:allowed?).and_call_original
+          allow(Ability).to receive(:allowed?).with(user, :read_group, group).and_return(false)
+
+          get api("/projects/#{project.id}/milestones", user),
+              params: { include_parent_milestones: true }
+
+          expect(response).to have_gitlab_http_status(:ok)
+          expect(json_response.size).to eq(2)
+        end
+      end
+
+      context 'when filtering by iids' do
+        it 'does not filer by iids' do
+          milestones = [group_milestone, milestone, closed_milestone]
+
+          get api("/projects/#{project.id}/milestones", user),
+              params: { include_parent_milestones: true, iids: [group_milestone.iid] }
+
+          expect(response).to have_gitlab_http_status(:ok)
+          expect(json_response.size).to eq(3)
+
+          expect(json_response.map { |entry| entry["id"] }).to eq(milestones.map(&:id))
+        end
+      end
+    end
+  end
+
   describe 'DELETE /projects/:id/milestones/:milestone_id' do
     let(:guest) { create(:user) }
     let(:reporter) { create(:user) }