Merge pull request #2123 from NARKOZ/notes-api

Notes API

CHANGELOG

 v 3.2.0
+  - [API] create notes for snippets and issues
+  - [API] list notes for snippets and issues
+  - [API] list project wall notes
   - Remove project code - use path instead
   - added username field to user
   - rake task to fill usernames based on emails create namespaces for users

app/views/help/api.html.haml

@@ -21,6 +21,8 @@
     = link_to "Issues", "#issues", 'data-toggle' => 'tab'
   %li
     = link_to "Milestones", "#milestones", 'data-toggle' => 'tab'
+  %li
+    = link_to "Notes", "#notes", 'data-toggle' => 'tab'
 
 .tab-content
   .tab-pane.active#README
@@ -94,3 +96,12 @@
       .file_content.wiki
         = preserve do
           = markdown File.read(Rails.root.join("doc", "api", "milestones.md"))
+
+  .tab-pane#notes
+    .file_holder
+      .file_title
+        %i.icon-file
+        Notes
+      .file_content.wiki
+        = preserve do
+          = markdown File.read(Rails.root.join("doc", "api", "notes.md"))

doc/api/notes.md

+## List notes
+
+### List project wall notes
+
+Get a list of project wall notes.
+
+```
+GET /projects/:id/notes
+```
+
+```json
+[
+  {
+    "id": 522,
+    "body": "The solution is rather tricky",
+    "author": {
+      "id": 1,
+      "email": "john@example.com",
+      "name": "John Smith",
+      "blocked": false,
+      "created_at": "2012-05-23T08:00:58Z"
+    },
+    "updated_at":"2012-11-27T19:16:44Z",
+    "created_at":"2012-11-27T19:16:44Z"
+  }
+]
+```
+
+Parameters:
+
++ `id` (required) - The ID or code name of a project
+
+### List issue notes
+
+Get a list of issue notes.
+
+```
+GET /projects/:id/issues/:issue_id/notes
+```
+
+Parameters:
+
++ `id` (required) - The ID or code name of a project
++ `issue_id` (required) - The ID of an issue
+
+### List snippet notes
+
+Get a list of snippet notes.
+
+```
+GET /projects/:id/snippets/:snippet_id/notes
+```
+
+Parameters:
+
++ `id` (required) - The ID or code name of a project
++ `snippet_id` (required) - The ID of a snippet
+
+## Single note
+
+### Single issue note
+
+Get an issue note.
+
+```
+GET /projects/:id/issues/:issue_id/:notes/:note_id
+```
+
+Parameters:
+
++ `id` (required) - The ID or code name of a project
++ `issue_id` (required) - The ID of a project issue
++ `note_id` (required) - The ID of an issue note
+
+### Single snippet note
+
+Get a snippet note.
+
+```
+GET /projects/:id/issues/:snippet_id/:notes/:note_id
+```
+
+Parameters:
+
++ `id` (required) - The ID or code name of a project
++ `snippet_id` (required) - The ID of a project snippet
++ `note_id` (required) - The ID of an snippet note
+
+## New note
+
+### New issue note
+
+Create a new issue note.
+
+```
+POST /projects/:id/issues/:issue_id/notes
+```
+
+Parameters:
+
++ `id` (required) - The ID or code name of a project
++ `issue_id` (required) - The ID of an issue
++ `body` (required) - The content of a note
+
+Will return created note with status `201 Created` on success, or `404 Not found` on fail.
+
+### New snippet note
+
+Create a new snippet note.
+
+```
+POST /projects/:id/snippets/:snippet_id/notes
+```
+
+Parameters:
+
++ `id` (required) - The ID or code name of a project
++ `snippet_id` (required) - The ID of an snippet
++ `body` (required) - The content of a note
+
+Will return created note with status `201 Created` on success, or `404 Not found` on fail.

lib/api.rb

@@ -19,5 +19,6 @@ module Gitlab
     mount Milestones
     mount Session
     mount MergeRequests
+    mount Notes
   end
 end

lib/api/entities.rb

@@ -70,8 +70,15 @@ module Gitlab
     end
 
     class Note < Grape::Entity
+      expose :id
+      expose :note, as: :body
       expose :author, using: Entities::UserBasic
+      expose :updated_at, :created_at
+    end
+
+    class MRNote < Grape::Entity
       expose :note
+      expose :author, using: Entities::UserBasic
     end
   end
 end

lib/api/merge_requests.rb

@@ -107,7 +107,7 @@ module Gitlab
         note.author = current_user
 
         if note.save
-          present note, with: Entities::Note
+          present note, with: Entities::MRNote
         else
           not_found!
         end

lib/api/notes.rb

+module Gitlab
+  # Notes API
+  class Notes < Grape::API
+    before { authenticate! }
+
+    NOTEABLE_TYPES = [Issue, Snippet]
+
+    resource :projects do
+      # Get a list of project wall notes
+      #
+      # Parameters:
+      #   id (required) - The ID or code name of a project
+      # Example Request:
+      #   GET /projects/:id/notes
+      get ":id/notes" do
+        @notes = user_project.common_notes
+        present paginate(@notes), with: Entities::Note
+      end
+
+      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 or code name 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}").find(params[:"#{noteable_id_str}"])
+          present paginate(@noteable.notes), with: Entities::Note
+        end
+
+        # Get a single +noteable+ note
+        #
+        # Parameters:
+        #   id (required) - The ID or code name 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}").find(params[:"#{noteable_id_str}"])
+          @note = @noteable.notes.find(params[:note_id])
+          present @note, with: Entities::Note
+        end
+
+        # Create a new +noteable+ note
+        #
+        # Parameters:
+        #   id (required) - The ID or code name of a project
+        #   noteable_id (required) - The ID of an issue or snippet
+        #   body (required) - The content of a note
+        # 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
+          @noteable = user_project.send(:"#{noteables_str}").find(params[:"#{noteable_id_str}"])
+          @note = @noteable.notes.new(note: params[:body])
+          @note.author = current_user
+          @note.project = user_project
+
+          if @note.save
+            present @note, with: Entities::Note
+          else
+            not_found!
+          end
+        end
+      end
+    end
+  end
+end

spec/requests/api/notes_spec.rb

+require 'spec_helper'
+
+describe Gitlab::API do
+  include ApiHelpers
+
+  let(:user) { create(:user) }
+  let!(:project) { create(:project, owner: user) }
+  let!(:issue) { create(:issue, project: project, author: user) }
+  let!(:snippet) { create(:snippet, project: project, author: user) }
+  let!(:issue_note) { create(:note, noteable: issue, project: project, author: user) }
+  let!(:snippet_note) { create(:note, noteable: snippet, project: project, author: user) }
+  let!(:wall_note) { create(:note, project: project, author: user) }
+  before { project.add_access(user, :read) }
+
+  describe "GET /projects/:id/notes" do
+    context "when unauthenticated" do
+      it "should return authentication error" do
+        get api("/projects/#{project.id}/notes")
+        response.status.should == 401
+      end
+    end
+
+    context "when authenticated" do
+      it "should return project wall notes" do
+        get api("/projects/#{project.id}/notes", user)
+        response.status.should == 200
+        json_response.should be_an Array
+        json_response.first['body'].should == wall_note.note
+      end
+    end
+  end
+
+  describe "GET /projects/:id/noteable/:noteable_id/notes" do
+    context "when noteable is an Issue" do
+      it "should return an array of issue notes" do
+        get api("/projects/#{project.id}/issues/#{issue.id}/notes", user)
+        response.status.should == 200
+        json_response.should be_an Array
+        json_response.first['body'].should == issue_note.note
+      end
+    end
+
+    context "when noteable is a Snippet" do
+      it "should return an array of snippet notes" do
+        get api("/projects/#{project.id}/snippets/#{snippet.id}/notes", user)
+        response.status.should == 200
+        json_response.should be_an Array
+        json_response.first['body'].should == snippet_note.note
+      end
+    end
+  end
+
+  describe "GET /projects/:id/noteable/:noteable_id/notes/:note_id" do
+    context "when noteable is an Issue" do
+      it "should return an issue note by id" do
+        get api("/projects/#{project.id}/issues/#{issue.id}/notes/#{issue_note.id}", user)
+        response.status.should == 200
+        json_response['body'].should == issue_note.note
+      end
+    end
+
+    context "when noteable is a Snippet" do
+      it "should return a snippet note by id" do
+        get api("/projects/#{project.id}/snippets/#{snippet.id}/notes/#{snippet_note.id}", user)
+        response.status.should == 200
+        json_response['body'].should == snippet_note.note
+      end
+    end
+  end
+
+  describe "POST /projects/:id/noteable/:noteable_id/notes" do
+    context "when noteable is an Issue" do
+      it "should create a new issue note" do
+        post api("/projects/#{project.id}/issues/#{issue.id}/notes", user), body: 'hi!'
+        response.status.should == 201
+        json_response['body'].should == 'hi!'
+        json_response['author']['email'].should == user.email
+      end
+    end
+
+    context "when noteable is a Snippet" do
+      it "should create a new snippet note" do
+        post api("/projects/#{project.id}/snippets/#{snippet.id}/notes", user), body: 'hi!'
+        response.status.should == 201
+        json_response['body'].should == 'hi!'
+        json_response['author']['email'].should == user.email
+      end
+    end
+  end
+end