Add API docs and correctly expose release api

Signed-off-by: Dmitriy Zaporozhets <dmitriy.zaporozhets@gmail.com>

3 files changed, 57 insertions, 26 deletions

diff --git a/doc/api/tags.md b/doc/api/tags.md
index dc69a0c6fbc..0113d4ba049 100644
--- a/doc/api/tags.md
+++ b/doc/api/tags.md
@@ -28,6 +28,10 @@ Parameters:
         "2a4b78934375d7f53875269ffd4f45fd83a84ebe"
       ]
     },
+    "release": {
+      "tag": "1.0.0",
+      "description": "Amazing release. Wow"
+    },
     "name": "v1.0.0",
     "message": null
   }
@@ -48,6 +52,7 @@ Parameters:
 - `tag_name` (required) - The name of a tag
 - `ref` (required) - Create tag using commit SHA, another tag name, or branch name.
 - `message` (optional) - Creates annotated tag.
+- `release_description` (optional) - Add release notes to the git tag and store it in the GitLab database.
 
 ```json
 {
@@ -64,6 +69,10 @@ Parameters:
       "2a4b78934375d7f53875269ffd4f45fd83a84ebe"
     ]
   },
+  "release": {
+    "tag": "1.0.0",
+    "description": "Amazing release. Wow"
+  },
   "name": "v1.0.0",
   "message": null
 }
@@ -73,3 +82,25 @@ it will contain the annotation.
 
 It returns 200 if the operation succeed. In case of an error,
 405 with an explaining error message is returned.
+
+
+## New release
+
+Add release notes to the existing git tag
+
+```
+PUT /projects/:id/repository/:tag/release
+```
+
+Parameters:
+
+- `id` (required) - The ID of a project
+- `tag` (required) - The name of a tag
+- `description` (required) - Release notes with markdown support
+
+```json
+{
+  "tag": "1.0.0",
+  "description": "Amazing release. Wow"
+}
+```
diff --git a/lib/api/entities.rb b/lib/api/entities.rb
index 7528e718c6f..3ca632dfae9 100644
--- a/lib/api/entities.rb
+++ b/lib/api/entities.rb
@@ -95,31 +95,6 @@ module API
       end
     end
 
-    class RepoTag < Grape::Entity
-      expose :name
-      expose :message do |repo_obj, _options|
-        if repo_obj.respond_to?(:message)
-          repo_obj.message
-        else
-          nil
-        end
-      end
-
-      expose :commit do |repo_obj, options|
-        if repo_obj.respond_to?(:commit)
-          repo_obj.commit
-        elsif options[:project]
-          options[:project].repository.commit(repo_obj.target)
-        end
-      end
-
-      expose :release do |repo_obj, options|
-        if options[:project]
-          options[:project].releases.find_by(tag: repo_obj.name)
-        end
-      end
-    end
-
     class RepoObject < Grape::Entity
       expose :name
 
@@ -351,5 +326,30 @@ module API
     class Release < Grape::Entity
       expose :tag, :description
     end
+
+    class RepoTag < Grape::Entity
+      expose :name
+      expose :message do |repo_obj, _options|
+        if repo_obj.respond_to?(:message)
+          repo_obj.message
+        else
+          nil
+        end
+      end
+
+      expose :commit do |repo_obj, options|
+        if repo_obj.respond_to?(:commit)
+          repo_obj.commit
+        elsif options[:project]
+          options[:project].repository.commit(repo_obj.target)
+        end
+      end
+
+      expose :release, using: Entities::Release do |repo_obj, options|
+        if options[:project]
+          options[:project].releases.find_by(tag: repo_obj.name)
+        end
+      end
+    end
   end
 end
diff --git a/lib/api/tags.rb b/lib/api/tags.rb
index 06fa1d23fd6..673342dd447 100644
--- a/lib/api/tags.rb
+++ b/lib/api/tags.rb
@@ -29,7 +29,7 @@ module API
         authorize_push_project
         message = params[:message] || nil
         result = CreateTagService.new(user_project, current_user).
-          execute(params[:tag_name], params[:ref], message)
+          execute(params[:tag_name], params[:ref], message, params[:release_description])
 
         if result[:status] == :success
           present result[:tag],