Expose epic in issues API

doc/api/issues.md

@@ -577,14 +577,22 @@ the `weight` parameter:
 ```
 
 Users on GitLab [Ultimate](https://about.gitlab.com/pricing/) will additionally see
-the `epic_iid` property:
+the `epic` property:
 
-```json
+```javascript
 {
    "project_id" : 4,
    "description" : "Omnis vero earum sunt corporis dolor et placeat.",
-   "epic_iid" : 42,
-   ...
+   "epic": {
+   "epic_iid" : 5, //deprecated, use `iid` of the `epic` attribute
+   "epic": {
+     "id" : 42,
+     "iid" : 5,
+     "title": "My epic epic",
+     "url" : "/groups/h5bp/-/epics/5",
+     "group_id": 8
+   },
+   // ...
 }
 ```
 
@@ -592,6 +600,9 @@ the `epic_iid` property:
 
 **Note**: The `closed_by` attribute was [introduced in GitLab 10.6][ce-17042]. This value will only be present for issues which were closed after GitLab 10.6 and when the user account that closed the issue still exists.
 
+**Note**: The `epic_iid` attribute is deprecated and [will be removed in 13.0](https://gitlab.com/gitlab-org/gitlab/issues/35157).
+Please use `iid` of the `epic` attribute instead.
+
 ## New issue
 
 Creates a new project issue.

ee/changelogs/unreleased/winh-issues-api-expose-epic.yml

+---
+title: Expose epic in issues API
+merge_request: 19300
+author:
+type: changed

ee/lib/ee/api/entities.rb

@@ -109,9 +109,12 @@ module EE
         extend ActiveSupport::Concern
 
         prepended do
-          expose :epic_iid,
-                 if: -> (issue, options) { ::Ability.allowed?(options[:current_user], :read_epic, issue.project&.group) } do |issue|
-            issue.epic&.iid
+          with_options if: -> (issue, options) { ::Ability.allowed?(options[:current_user], :read_epic, issue.project&.group) } do
+            expose :epic_iid do |issue|
+              issue.epic&.iid
+            end
+
+            expose :epic, using: EpicBaseEntity
           end
         end
       end

ee/spec/fixtures/api/schemas/public_api/v4/issues.json

@@ -5,7 +5,17 @@
     {
       "properties": {
         "weight": { "type": ["integer", "null"] },
-        "epic_iid": { "type": ["integer", "null"] }
+        "epic_iid": { "type": ["integer", "null"] },
+        "epic": {
+          "type": "object",
+          "properties": {
+            "id": { "type": "integer" },
+            "iid": { "type": "integer" },
+            "group_id": { "type": "integer" },
+            "title": { "type": "string" },
+            "url": { "type": "string" }
+          }
+        }
       }
     }
   ]

ee/spec/requests/api/issues_spec.rb

@@ -33,7 +33,7 @@ describe API::Issues, :mailer do
     project.add_reporter(user)
   end
 
-  shared_examples 'exposes epic_iid' do
+  shared_examples 'exposes epic' do
     context 'with epics feature' do
       before do
         stub_licensed_features(epics: true)
@@ -45,6 +45,17 @@ describe API::Issues, :mailer do
         expect(response).to have_gitlab_http_status(:success)
         expect(epic_issue_response_for(epic_issue)['epic_iid']).to eq(epic.iid)
       end
+
+      it 'contains epic in response' do
+        subject
+
+        expect(response).to have_gitlab_http_status(:success)
+        expect(epic_issue_response_for(epic_issue)['epic']).to eq({ "id" => epic.id,
+                                                                    "iid" => epic.iid,
+                                                                    "group_id" => epic.group_id,
+                                                                    "title" => epic.title,
+                                                                    "url" => group_epic_path(epic.group, epic) })
+      end
     end
 
     context 'without epics feature' do
@@ -58,6 +69,13 @@ describe API::Issues, :mailer do
         expect(response).to have_gitlab_http_status(:success)
         expect(epic_issue_response_for(epic_issue)).not_to have_key('epic_iid')
       end
+
+      it 'does not contain epic_iid in response' do
+        subject
+
+        expect(response).to have_gitlab_http_status(:success)
+        expect(epic_issue_response_for(epic_issue)).not_to have_key('epic')
+      end
     end
   end
 
@@ -175,7 +193,7 @@ describe API::Issues, :mailer do
       end
     end
 
-    include_examples 'exposes epic_iid' do
+    include_examples 'exposes epic' do
       let!(:epic_issue) { create(:issue, project: group_project, epic: epic) }
     end
   end
@@ -221,7 +239,7 @@ describe API::Issues, :mailer do
 
       subject { get api("/projects/#{group_project.id}/issues", user) }
 
-      include_examples 'exposes epic_iid'
+      include_examples 'exposes epic'
     end
   end
 
@@ -248,7 +266,7 @@ describe API::Issues, :mailer do
 
       subject { get api("/projects/#{group_project.id}/issues/#{epic_issue.iid}", user) }
 
-      include_examples 'exposes epic_iid'
+      include_examples 'exposes epic'
     end
   end
 
@@ -278,7 +296,7 @@ describe API::Issues, :mailer do
           group.add_owner(user)
         end
 
-        include_examples 'exposes epic_iid'
+        include_examples 'exposes epic'
         include_examples 'sets epic_iid'
       end
 
@@ -348,7 +366,7 @@ describe API::Issues, :mailer do
         group.add_owner(user)
       end
 
-      include_examples 'exposes epic_iid'
+      include_examples 'exposes epic'
       include_examples 'sets epic_iid'
     end