1 files changed, 34 insertions, 15 deletions

diff --git a/lib/api/admin/ci/variables.rb b/lib/api/admin/ci/variables.rb
index 0462878c90c..bc351e27f99 100644
--- a/lib/api/admin/ci/variables.rb
+++ b/lib/api/admin/ci/variables.rb
@@ -13,8 +13,9 @@ module API
         namespace 'admin' do
           namespace 'ci' do
             namespace 'variables' do
-              desc 'Get instance-level variables' do
+              desc 'List all instance-level variables' do
                 success Entities::Ci::Variable
+                tags %w[ci_variables]
               end
               params do
                 use :pagination
@@ -25,11 +26,13 @@ module API
                 present paginate(variables), with: Entities::Ci::Variable
               end
 
-              desc 'Get a specific variable from a group' do
+              desc 'Get the details of a specific instance-level variable' do
                 success Entities::Ci::Variable
+                failure [{ code: 404, message: 'Instance Variable Not Found' }]
+                tags %w[ci_variables]
               end
               params do
-                requires :key, type: String, desc: 'The key of the variable'
+                requires :key, type: String, desc: 'The key of a variable'
               end
               get ':key' do
                 key = params[:key]
@@ -42,28 +45,35 @@ module API
 
               desc 'Create a new instance-level variable' do
                 success Entities::Ci::Variable
+                failure [{ code: 400, message: '400 Bad Request' }]
+                tags %w[ci_variables]
               end
+              route_setting :log_safety, { safe: %w[key], unsafe: %w[value] }
               params do
                 requires :key,
                   type: String,
-                  desc: 'The key of the variable'
+                  desc: 'The key of the variable. Max 255 characters'
 
                 requires :value,
                   type: String,
-                  desc: 'The value of the variable'
+                  desc: 'The value of a variable'
 
                 optional :protected,
-                  type: String,
+                  type: Boolean,
                   desc: 'Whether the variable is protected'
 
                 optional :masked,
-                  type: String,
+                  type: Boolean,
                   desc: 'Whether the variable is masked'
 
+                optional :raw,
+                  type: Boolean,
+                  desc: 'Whether the variable will be expanded'
+
                 optional :variable_type,
                   type: String,
                   values: ::Ci::InstanceVariable.variable_types.keys,
-                  desc: 'The type of variable, must be one of env_var or file. Defaults to env_var'
+                  desc: 'The type of a variable. Available types are: env_var (default) and file'
               end
               post '/' do
                 variable_params = declared_params(include_missing: false)
@@ -77,30 +87,37 @@ module API
                 end
               end
 
-              desc 'Update an existing instance-variable' do
+              desc 'Update an instance-level variable' do
                 success Entities::Ci::Variable
+                failure [{ code: 404, message: 'Instance Variable Not Found' }]
+                tags %w[ci_variables]
               end
+              route_setting :log_safety, { safe: %w[key], unsafe: %w[value] }
               params do
                 optional :key,
                   type: String,
-                  desc: 'The key of the variable'
+                  desc: 'The key of a variable'
 
                 optional :value,
                   type: String,
-                  desc: 'The value of the variable'
+                  desc: 'The value of a variable'
 
                 optional :protected,
-                  type: String,
+                  type: Boolean,
                   desc: 'Whether the variable is protected'
 
                 optional :masked,
-                  type: String,
+                  type: Boolean,
                   desc: 'Whether the variable is masked'
 
+                optional :raw,
+                  type: Boolean,
+                  desc: 'Whether the variable will be expanded'
+
                 optional :variable_type,
                   type: String,
                   values: ::Ci::InstanceVariable.variable_types.keys,
-                  desc: 'The type of variable, must be one of env_var or file'
+                  desc: 'The type of a variable. Available types are: env_var (default) and file'
               end
               put ':key' do
                 variable = ::Ci::InstanceVariable.find_by_key(params[:key])
@@ -118,9 +135,11 @@ module API
 
               desc 'Delete an existing instance-level variable' do
                 success Entities::Ci::Variable
+                failure [{ code: 404, message: 'Instance Variable Not Found' }]
+                tags %w[ci_variables]
               end
               params do
-                requires :key, type: String, desc: 'The key of the variable'
+                requires :key, type: String, desc: 'The key of a variable'
               end
               delete ':key' do
                 variable = ::Ci::InstanceVariable.find_by_key(params[:key])