1 files changed, 11 insertions, 5 deletions
diff --git a/lib/api/markdown.rb b/lib/api/markdown.rb
index 1f8255fd6a4..276560f3433 100644
--- a/lib/api/markdown.rb
+++ b/lib/api/markdown.rb
@@ -7,13 +7,19 @@ module API
     feature_category :team_planning
 
     params do
-      requires :text, type: String, desc: "The markdown text to render"
-      optional :gfm, type: Boolean, desc: "Render text using GitLab Flavored Markdown"
-      optional :project, type: String, desc: "The full path of a project to use as the context when creating references using GitLab Flavored Markdown"
+      requires :text, type: String, desc: "The Markdown text to render"
+      optional :gfm, type: Boolean, desc: "Render text using GitLab Flavored Markdown. Default is false"
+      optional :project, type: String, desc: "Use project as a context when creating references using GitLab Flavored Markdown"
     end
     resource :markdown do
-      desc "Render markdown text" do
+      desc "Render an arbitrary Markdown document" do
         detail "This feature was introduced in GitLab 11.0."
+        success ::API::Entities::Markdown
+        failure [
+          { code: 400, message: 'Bad request' },
+          { code: 401, message: 'Unauthorized' }
+        ]
+        tags %w[markdown]
       end
       post do
         context = { only_path: false, current_user: current_user }
@@ -29,7 +35,7 @@ module API
           context[:skip_project_check] = true
         end
 
-        { html: Banzai.render_and_post_process(params[:text], context) }
+        present({ html: Banzai.render_and_post_process(params[:text], context) }, with: Entities::Markdown)
       end
     end
   end