Add specs for job token and add doc examples

Add specs to prove that prove job_token_allowed: :basic_auth
is inclusive of the functionality in `job_token_allowed: true`

doc/api/jobs.md

@@ -400,11 +400,13 @@ Retrieve the job that generated a job token.
 GET /job
 ```
 
-Examples
+Examples (within GitLab CI YAML)
 
-```shell
-curl --header "JOB-TOKEN: <your_job_token>" "https://gitlab.example.com/api/v4/job"
-curl "https://gitlab.example.com/api/v4/job?job_token=<your_job_token>"
+```yaml
+  script:
+    - 'curl --header "Authorization: Bearer $CI_JOB_TOKEN" "${CI_API_V4_URL}/job"'
+    - 'curl --header "JOB-TOKEN: $CI_JOB_TOKEN" "${CI_API_V4_URL}/job"'
+    - 'curl "${CI_API_V4_URL}/job?job_token=$CI_JOB_TOKEN"'
 ```
 
 Example of response

spec/lib/gitlab/auth/auth_finders_spec.rb

@@ -873,45 +873,65 @@ RSpec.describe Gitlab::Auth::AuthFinders do
   end
 
   describe '#find_user_from_job_token' do
+    let(:token) { job.token }
+
     subject { find_user_from_job_token }
 
-    context 'when the token is in the headers' do
-      before do
-        set_header(described_class::JOB_TOKEN_HEADER, token)
+    shared_examples 'finds user when job token allowed' do
+      context 'when the token is in the headers' do
+        before do
+          set_header(described_class::JOB_TOKEN_HEADER, token)
+        end
+
+        it_behaves_like 'find user from job token'
       end
 
-      it_behaves_like 'find user from job token'
-    end
+      context 'when the token is in the job_token param' do
+        before do
+          set_param(described_class::JOB_TOKEN_PARAM, token)
+        end
 
-    context 'when the token is in the job_token param' do
-      before do
-        set_param(described_class::JOB_TOKEN_PARAM, token)
+        it_behaves_like 'find user from job token'
       end
 
-      it_behaves_like 'find user from job token'
-    end
+      context 'when the token is in the token param' do
+        before do
+          set_param(described_class::RUNNER_JOB_TOKEN_PARAM, token)
+        end
 
-    context 'when the token is in the token param' do
-      before do
-        set_param(described_class::RUNNER_JOB_TOKEN_PARAM, token)
+        it_behaves_like 'find user from job token'
       end
+    end
 
-      it_behaves_like 'find user from job token'
+    context 'when route setting allows job_token' do
+      let(:route_authentication_setting) { { job_token_allowed: true } }
+
+      include_examples 'finds user when job token allowed'
     end
 
-    context 'when the job token is provided via basic auth' do
+    context 'when route setting is basic auth' do
       let(:route_authentication_setting) { { job_token_allowed: :basic_auth } }
-      let(:username) { ::Gitlab::Auth::CI_JOB_USER }
-      let(:token) { job.token }
 
-      before do
-        set_basic_auth_header(username, token)
+      context 'when the token is provided via basic auth' do
+        let(:username) { ::Gitlab::Auth::CI_JOB_USER }
+
+        before do
+          set_basic_auth_header(username, token)
+        end
+
+        it { is_expected.to eq(user) }
       end
 
-      it { is_expected.to eq(user) }
+      include_examples 'finds user when job token allowed'
+    end
 
-      context 'credentials are provided but route setting is incorrect' do
-        let(:route_authentication_setting) { { job_token_allowed: :unknown } }
+    context 'when route setting job_token_allowed is invalid' do
+      let(:route_authentication_setting) { { job_token_allowed: false } }
+
+      context 'when the token is provided' do
+        before do
+          set_header(described_class::JOB_TOKEN_HEADER, token)
+        end
 
         it { is_expected.to be_nil }
       end