Merge branch 'nd/api-epic-link-documentation' into 'master'

Add Open API documentation for EpicLinks

See merge request https://gitlab.com/gitlab-org/gitlab/-/merge_requests/105405



Merged-by: Doug Stull <dstull@gitlab.com>
Approved-by: Jon Jenkins <jjenkins@gitlab.com>
Approved-by: Doug Stull <dstull@gitlab.com>
Co-authored-by: Nicolas Dular <ndular@gitlab.com>

ee/lib/api/epic_links.rb

@@ -47,18 +47,27 @@ def cross_group_child_epics_enabled?
 
       params :child_epic_id do
         # Unique ID should be used because epics from other groups can be assigned as child.
-        requires :child_epic_id, type: Integer, desc: 'The global ID of the epic that will be assigned as child'
+        requires :child_epic_id,
+          type: Integer,
+          desc: "The global ID of the child epic. Internal ID can't be used because they can conflict with epics from other groups.",
+          documentation: { example: 1 }
       end
     end
 
     params do
-      requires :id, type: String, desc: 'The ID of a group'
-      requires :epic_iid, type: Integer, desc: 'The internal ID of an epic'
+      requires :id, type: String, desc: 'The ID of a group', documentation: { example: '1' }
+      requires :epic_iid, type: Integer, desc: 'The internal ID of an epic', documentation: { example: 1 }
     end
 
     resource :groups, requirements: API::NAMESPACE_OR_PROJECT_REQUIREMENTS do
       desc 'Get related epics' do
         success EE::API::Entities::Epic
+        is_array true
+        failure [
+          { code: 401, message: 'Unauthorized' },
+          { code: 403, message: 'Forbidden' },
+          { code: 404, message: 'Not found' }
+        ]
       end
       get ':id/(-/)epics/:epic_iid/epics' do
         authorize_epics_feature!
@@ -69,6 +78,12 @@ def cross_group_child_epics_enabled?
 
       desc 'Relate epics' do
         success EE::API::Entities::Epic
+        failure [
+          { code: 401, message: 'Unauthorized' },
+          { code: 403, message: 'Forbidden' },
+          { code: 404, message: 'Not found' },
+          { code: 409, message: 'Conflict' }
+        ]
       end
       params do
         use :child_epic_id
@@ -92,10 +107,19 @@ def cross_group_child_epics_enabled?
 
       desc 'Create and relate epic to a parent' do
         success EE::API::Entities::Epic
+        failure [
+          { code: 401, message: 'Unauthorized' },
+          { code: 403, message: 'Forbidden' },
+          { code: 404, message: 'Not found' },
+          { code: 409, message: 'Conflict' }
+        ]
       end
       params do
-        requires :title, type: String, desc: 'The title of a child epic'
-        optional :confidential, type: Boolean, desc: 'Indicates if the epic is confidential. Will be ignored if `confidential_epics` feature flag is disabled'
+        requires :title, type: String, desc: 'The title of a child epic', documentation: { example: "Epic title" }
+        optional :confidential,
+          type: Boolean,
+          desc: "Whether the epic should be confidential. Parameter is ignored if `confidential_epics`` feature flag is disabled. Defaults to the confidentiality state of the parent epic.",
+          documentation: { example: true }
       end
       post ':id/(-/)epics/:epic_iid/epics' do
         authorize_subepics_feature!
@@ -113,7 +137,13 @@ def cross_group_child_epics_enabled?
         end
       end
 
-      desc 'Remove epics relation'
+      desc 'Remove epics relation' do
+        success EE::API::Entities::Epic
+        failure [
+          { code: 401, message: 'Unauthorized' },
+          { code: 404, message: 'Not found' }
+        ]
+      end
       params do
         use :child_epic_id
       end
@@ -129,11 +159,23 @@ def cross_group_child_epics_enabled?
         end
       end
 
-      desc 'Reorder child epics'
+      desc 'Reorder child epics' do
+        success EE::API::Entities::Epic
+        failure [
+          { code: 401, message: 'Unauthorized' },
+          { code: 404, message: 'Not found' }
+        ]
+      end
       params do
         use :child_epic_id
-        optional :move_before_id, type: Integer, desc: 'The ID of the epic that should be positioned before the child epic'
-        optional :move_after_id, type: Integer, desc: 'The ID of the epic that should be positioned after the child epic'
+        optional :move_before_id,
+          type: Integer,
+          desc: 'The ID of the epic that should be positioned before the child epic',
+          documentation: { example: 1 }
+        optional :move_after_id,
+          type: Integer,
+          desc: 'The ID of the epic that should be positioned after the child epic',
+          documentation: { example: 1 }
       end
       put ':id/(-/)epics/:epic_iid/epics/:child_epic_id' do
         authorize_subepics_feature!