Apply 2 suggestion(s) to 1 file(s)

doc/api/releases/index.md

@@ -10,8 +10,8 @@ info: To determine the technical writer assigned to the Stage/Group associated w
 > - Using this API you can manipulate GitLab [Release](../../user/project/releases/index.md) entries.
 > - For manipulating links as a release asset, see [Release Links API](links.md).
 > - Release Evidences were [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/26019) in GitLab 12.5.
-> - `description_html` became and opt-in field [in GitLab 13.12 for performance reason](https://gitlab.com/gitlab-org/gitlab/-/issues/299447).
-    Please pass `render_html` option if you need.
+> - `description_html` became an opt-in field [with GitLab 13.12 for performance reasons](https://gitlab.com/gitlab-org/gitlab/-/issues/299447).
+    Please pass the `include_html_description` query string parameter if you need it.
 
 ## List Releases
 
@@ -26,7 +26,7 @@ GET /projects/:id/releases
 | `id`          | integer/string | yes      | The ID or [URL-encoded path of the project](../README.md#namespaced-path-encoding). |
 | `order_by`    | string         | no       | The field to use as order. Either `released_at` (default) or `created_at`. |
 | `sort`        | string         | no       | The direction of the order. Either `desc` (default) for descending order or `asc` for ascending order. |
-| `render_html` | boolean        | no       | If `true`, a response includes HTML rendered Markdown of the release description.   |
+| `include_html_description` | boolean        | no       | If `true`, a response includes HTML rendered Markdown of the release description.   |
 
 Example request:
 
@@ -230,7 +230,7 @@ GET /projects/:id/releases/:tag_name
 | ------------- | -------------- | -------- | ----------------------------------------------------------------------------------- |
 | `id`          | integer/string | yes      | The ID or [URL-encoded path of the project](../README.md#namespaced-path-encoding). |
 | `tag_name`    | string         | yes      | The Git tag the release is associated with.                                         |
-| `render_html` | boolean        | no       | If `true`, a response includes HTML rendered Markdown of the release description.   |
+| `include_html_description` | boolean        | no       | If `true`, a response includes HTML rendered Markdown of the release description.   |
 
 Example request:
 

lib/api/entities/release.rb

@@ -8,7 +8,7 @@ module API
       expose :name
       expose :tag, as: :tag_name, if: ->(_, _) { can_download_code? }
       expose :description
-      expose :description_html, if: -> (_, options) { options[:render_html] } do |entity|
+      expose :description_html, if: -> (_, options) { options[:include_html_description] } do |entity|
         MarkupHelper.markdown_field(entity, :description, current_user: options[:current_user])
       end
       expose :created_at

lib/api/releases.rb

@@ -29,7 +29,7 @@ module API
                             desc: 'Return releases ordered by `released_at` or `created_at`.'
         optional :sort, type: String, values: %w[asc desc], default: 'desc',
                         desc: 'Return releases sorted in `asc` or `desc` order.'
-        optional :render_html, type: Boolean,
+        optional :include_html_description, type: Boolean,
                                desc: 'If `true`, a response includes HTML rendered markdown of the release description.'
       end
       get ':id/releases' do
@@ -46,7 +46,7 @@ module API
                         cache_context: -> (_) { "user:{#{current_user&.id}}" },
                         expires_in: 5.minutes,
                         current_user: current_user,
-                        render_html: params[:render_html]
+                        include_html_description: params[:include_html_description]
       end
 
       desc 'Get a single project release' do
@@ -56,13 +56,13 @@ module API
       end
       params do
         requires :tag_name, type: String, desc: 'The name of the tag', as: :tag
-        optional :render_html, type: Boolean,
+        optional :include_html_description, type: Boolean,
                                desc: 'If `true`, a response includes HTML rendered markdown of the release description.'
       end
       get ':id/releases/:tag_name', requirements: RELEASE_ENDPOINT_REQUIREMENTS do
         authorize_download_code!
 
-        present release, with: Entities::Release, current_user: current_user, render_html: params[:render_html]
+        present release, with: Entities::Release, current_user: current_user, include_html_description: params[:include_html_description]
       end
 
       desc 'Create a new release' do

spec/lib/api/entities/release_spec.rb

@@ -8,8 +8,8 @@ RSpec.describe API::Entities::Release do
   let(:release) { create(:release, project: project) }
   let(:evidence) { release.evidences.first }
   let(:user) { create(:user) }
-  let(:entity) { described_class.new(release, current_user: user, render_html: render_html).as_json }
-  let(:render_html) { false }
+  let(:entity) { described_class.new(release, current_user: user, include_html_description: include_html_description).as_json }
+  let(:include_html_description) { false }
 
   before do
     ::Releases::CreateEvidenceService.new(release).execute
@@ -59,8 +59,8 @@ RSpec.describe API::Entities::Release do
       expect(description_html).to be_nil
     end
 
-    context 'when render_html option is true' do
-      let(:render_html) { true }
+    context 'when include_html_description option is true' do
+      let(:include_html_description) { true }
 
       it 'renders special references if current user has access' do
         project.add_reporter(user)

spec/requests/api/releases_spec.rb

@@ -114,9 +114,9 @@ RSpec.describe API::Releases do
         expect(json_response.second['tag_path']).to eq("/#{release_1.project.full_path}/-/tags/#{release_1.tag}")
       end
 
-      context 'when render_html option is true' do
+      context 'when include_html_description option is true' do
         it 'includes description_html field' do
-          get api("/projects/#{project.id}/releases", maintainer), params: { render_html: true }
+          get api("/projects/#{project.id}/releases", maintainer), params: { include_html_description: true }
 
           expect(json_response.map { |h| h['description_html'] })
             .to contain_exactly(instance_of(String), instance_of(String))
@@ -424,9 +424,9 @@ RSpec.describe API::Releases do
         end
       end
 
-      context 'when render_html option is true' do
+      context 'when include_html_description option is true' do
         it 'includes description_html field' do
-          get api("/projects/#{project.id}/releases/v0.1", maintainer), params: { render_html: true }
+          get api("/projects/#{project.id}/releases/v0.1", maintainer), params: { include_html_description: true }
 
           expect(json_response['description_html']).to be_instance_of(String)
         end