Merge remote-tracking branch 'upstream/master' into feature/1376-allow-write-access-deploy-keys

* upstream/master: (236 commits)
  Mention Git strategy none
  Remove ToC since it's now supported in the docs portal itself
  Add 8.14 to versions with further additions to review apps
  Add Limitations sections to environments and review apps docs
  Add link to environments docs
  Fix URL to review apps docs
  Add a prerequisites section, add some links
  Link to NGINX example project for the time being
  Get rid most of the irrelevant sections
  Add note about current limitation in $CI_BUILD_REF_NAME
  Add an intro and an Overview section for Review Apps
  WIP review apps
  Add Review apps link to CI README
  Add stop environment permissions and remove delete
  Add note about auto-stopping of environments
  Update CHANGELOG.md for 8.13.6
  Finish "Stopping envs" and "Grouping similar envs" sections
  Highlight first user autocomplete option
  Remove ToC and fix headings in Markdown docs
  Revert "Merge branch '22680-unlabel-limit-autocomplete-to-selected-items' into 'master'"
  ...

1 files changed, 57 insertions, 67 deletions

diff --git a/lib/api/notes.rb b/lib/api/notes.rb
index c5c214d4d13..b255b47742b 100644
--- a/lib/api/notes.rb
+++ b/lib/api/notes.rb
@@ -5,23 +5,23 @@ module API
 
     NOTEABLE_TYPES = [Issue, MergeRequest, Snippet]
 
+    params do
+      requires :id, type: String, desc: 'The ID of a project'
+    end
     resource :projects do
       NOTEABLE_TYPES.each do |noteable_type|
         noteables_str = noteable_type.to_s.underscore.pluralize
-        noteable_id_str = "#{noteable_type.to_s.underscore}_id"
-
-        # Get a list of project +noteable+ notes
-        #
-        # Parameters:
-        #   id (required) - The ID of a project
-        #   noteable_id (required) - The ID of an issue or snippet
-        # Example Request:
-        #   GET /projects/:id/issues/:noteable_id/notes
-        #   GET /projects/:id/snippets/:noteable_id/notes
-        get ":id/#{noteables_str}/:#{noteable_id_str}/notes" do
-          @noteable = user_project.send(noteables_str.to_sym).find(params[noteable_id_str.to_sym])
-
-          if can?(current_user, noteable_read_ability_name(@noteable), @noteable)
+
+        desc 'Get a list of project +noteable+ notes' do
+          success Entities::Note
+        end
+        params do
+          requires :noteable_id, type: Integer, desc: 'The ID of the noteable'
+        end
+        get ":id/#{noteables_str}/:noteable_id/notes" do
+          noteable = user_project.send(noteables_str.to_sym).find(params[:noteable_id])
+
+          if can?(current_user, noteable_read_ability_name(noteable), noteable)
             # We exclude notes that are cross-references and that cannot be viewed
             # by the current user. By doing this exclusion at this level and not
             # at the DB query level (which we cannot in that case), the current
@@ -31,7 +31,7 @@ module API
               # paginate() only works with a relation. This could lead to a
               # mismatch between the pagination headers info and the actual notes
               # array returned, but this is really a edge-case.
-              paginate(@noteable.notes).
+              paginate(noteable.notes).
               reject { |n| n.cross_reference_not_visible_for?(current_user) }
             present notes, with: Entities::Note
           else
@@ -39,44 +39,40 @@ module API
           end
         end
 
-        # Get a single +noteable+ note
-        #
-        # Parameters:
-        #   id (required) - The ID of a project
-        #   noteable_id (required) - The ID of an issue or snippet
-        #   note_id (required) - The ID of a note
-        # Example Request:
-        #   GET /projects/:id/issues/:noteable_id/notes/:note_id
-        #   GET /projects/:id/snippets/:noteable_id/notes/:note_id
-        get ":id/#{noteables_str}/:#{noteable_id_str}/notes/:note_id" do
-          @noteable = user_project.send(noteables_str.to_sym).find(params[noteable_id_str.to_sym])
-          @note = @noteable.notes.find(params[:note_id])
-          can_read_note = can?(current_user, noteable_read_ability_name(@noteable), @noteable) && !@note.cross_reference_not_visible_for?(current_user)
+        desc 'Get a single +noteable+ note' do
+          success Entities::Note
+        end
+        params do
+          requires :note_id, type: Integer, desc: 'The ID of a note'
+          requires :noteable_id, type: Integer, desc: 'The ID of the noteable'
+        end
+        get ":id/#{noteables_str}/:noteable_id/notes/:note_id" do
+          noteable = user_project.send(noteables_str.to_sym).find(params[:noteable_id])
+          note = noteable.notes.find(params[:note_id])
+          can_read_note = can?(current_user, noteable_read_ability_name(noteable), noteable) && !note.cross_reference_not_visible_for?(current_user)
 
           if can_read_note
-            present @note, with: Entities::Note
+            present note, with: Entities::Note
           else
             not_found!("Note")
           end
         end
 
-        # Create a new +noteable+ note
-        #
-        # Parameters:
-        #   id (required) - The ID of a project
-        #   noteable_id (required) - The ID of an issue or snippet
-        #   body (required) - The content of a note
-        #   created_at (optional) - The date
-        # Example Request:
-        #   POST /projects/:id/issues/:noteable_id/notes
-        #   POST /projects/:id/snippets/:noteable_id/notes
-        post ":id/#{noteables_str}/:#{noteable_id_str}/notes" do
+        desc 'Create a new +noteable+ note' do
+          success Entities::Note
+        end
+        params do
+          requires :noteable_id, type: Integer, desc: 'The ID of the noteable'
+          requires :body, type: String, desc: 'The content of a note'
+          optional :created_at, type: String, desc: 'The creation date of the note'
+        end
+        post ":id/#{noteables_str}/:noteable_id/notes" do
           required_attributes! [:body]
 
           opts = {
            note: params[:body],
            noteable_type: noteables_str.classify,
-           noteable_id: params[noteable_id_str]
+           noteable_id: params[:noteable_id]
           }
 
           if params[:created_at] && (current_user.is_admin? || user_project.owner == current_user)
@@ -92,19 +88,15 @@ module API
           end
         end
 
-        # Modify existing +noteable+ note
-        #
-        # Parameters:
-        #   id (required) - The ID of a project
-        #   noteable_id (required) - The ID of an issue or snippet
-        #   node_id (required) - The ID of a note
-        #   body (required) - New content of a note
-        # Example Request:
-        #   PUT /projects/:id/issues/:noteable_id/notes/:note_id
-        #   PUT /projects/:id/snippets/:noteable_id/notes/:node_id
-        put ":id/#{noteables_str}/:#{noteable_id_str}/notes/:note_id" do
-          required_attributes! [:body]
-
+        desc 'Update an existing +noteable+ note' do
+          success Entities::Note
+        end
+        params do
+          requires :noteable_id, type: Integer, desc: 'The ID of the noteable'
+          requires :note_id, type: Integer, desc: 'The ID of a note'
+          requires :body, type: String, desc: 'The content of a note'
+        end
+        put ":id/#{noteables_str}/:noteable_id/notes/:note_id" do
           note = user_project.notes.find(params[:note_id])
 
           authorize! :admin_note, note
@@ -113,25 +105,23 @@ module API
             note: params[:body]
           }
 
-          @note = ::Notes::UpdateService.new(user_project, current_user, opts).execute(note)
+          note = ::Notes::UpdateService.new(user_project, current_user, opts).execute(note)
 
-          if @note.valid?
-            present @note, with: Entities::Note
+          if note.valid?
+            present note, with: Entities::Note
           else
             render_api_error!("Failed to save note #{note.errors.messages}", 400)
           end
         end
 
-        # Delete a +noteable+ note
-        #
-        # Parameters:
-        #   id (required) - The ID of a project
-        #   noteable_id (required) - The ID of an issue, MR, or snippet
-        #   node_id (required) - The ID of a note
-        # Example Request:
-        #   DELETE /projects/:id/issues/:noteable_id/notes/:note_id
-        #   DELETE /projects/:id/snippets/:noteable_id/notes/:node_id
-        delete ":id/#{noteables_str}/:#{noteable_id_str}/notes/:note_id" do
+        desc 'Delete a +noteable+ note' do
+          success Entities::Note
+        end
+        params do
+          requires :noteable_id, type: Integer, desc: 'The ID of the noteable'
+          requires :note_id, type: Integer, desc: 'The ID of a note'
+        end
+        delete ":id/#{noteables_str}/:noteable_id/notes/:note_id" do
           note = user_project.notes.find(params[:note_id])
           authorize! :admin_note, note