Resolve $ref in response header objects

lib/openapi_contracts/doc/response.rb

@@ -11,11 +11,9 @@ def initialize(operation, status, schema)
     end
 
     def headers
-      return @headers if instance_variable_defined? :@headers
-
-      @headers = @schema.fetch('headers', {}).map do |(key, val)|
-        Doc::Header.new(key, val)
-      end
+      @headers ||= Array.wrap(
+        @schema.navigate('headers')&.each&.map { |key, schema| Doc::Header.new(key, schema.to_h) }
+      )
     end
 
     def schema_for(media_type)

spec/fixtures/openapi/components/headers/TraceId.yaml

@@ -0,0 +1,4 @@
+description: Distributed trace identifier.
+schema:
+  type: string
+  format: uuid

spec/fixtures/openapi/paths/user.yaml

@@ -12,6 +12,8 @@ get:
           schema:
             type: string
           required: true
+        x-trace-id:
+          $ref: ../components/headers/TraceId.yaml
       content:
         application/json:
           schema:

spec/openapi_contracts/doc/response_spec.rb

@@ -59,5 +59,24 @@
         it { is_expected.to be_nil }
       end
     end
+
+    describe '#headers' do
+      context 'when a header is defined inline' do
+        subject(:header) { response.headers.find { |h| h.name == 'x-request-id' } }
+
+        it 'exposes its schema' do
+          expect(header.schema).to eq('type' => 'string')
+          expect(header.required?).to be true
+        end
+      end
+
+      context 'when a header is defined via $ref' do
+        subject(:header) { response.headers.find { |h| h.name == 'x-trace-id' } }
+
+        it 'follows the ref and exposes the referenced schema' do
+          expect(header.schema).to eq('type' => 'string', 'format' => 'uuid')
+        end
+      end
+    end
   end
 end

spec/openapi_contracts/validators/headers_spec.rb

@@ -46,4 +46,28 @@
       ]
     end
   end
+
+  context 'when a header is defined via $ref' do
+    context 'when its value matches the referenced schema' do
+      before do
+        response_headers['x-trace-id'] = '550e8400-e29b-41d4-a716-446655440000'
+      end
+
+      it 'resolves the ref and has no errors' do
+        expect(subject.call).to be_empty
+      end
+    end
+
+    context 'when its value violates the referenced schema' do
+      before do
+        response_headers['x-trace-id'] = 1
+      end
+
+      it 'returns the error' do
+        expect(subject.call).to eq [
+          'Header x-trace-id validation error: value at root is not a string (value: 1)'
+        ]
+      end
+    end
+  end
 end