Fix #60: resolve $ref in response headers pointing to #/components/headers/ (#72)

Response header definitions using $ref (e.g. $ref: '#/components/headers/foo')
were passed to Jinja templates unresolved, causing an UndefinedError when the
template accessed .schema or .description.

Added get_response_headers() method to OpenAPIV3DocumentationHandler that
calls _resolve_opt_ref() on each header value before returning the dict.
Updated both mkdocs and markdown request-responses templates to call this
method instead of iterating definition.headers directly.

Added regression test with a fixture (example9-openapi.yaml) covering
both $ref headers and inline headers in the same response.

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

Author: RobertoPrevato

CHANGELOG.md

@@ -23,6 +23,9 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
   fragment), reported by @mbklein.
 - Fix [#55](https://github.com/Neoteroi/essentials-openapi/issues/55): `jsonSchemaDialect`
   is not required and should not have a default value.
+- Fix [#60](https://github.com/Neoteroi/essentials-openapi/issues/60): resolve `$ref`
+  values in response headers pointing to `#/components/headers/...` to avoid
+  `UndefinedError` when rendering response tables, reported by @copiousfreetime.
 
 ## [1.3.0] - 2025-11-19
 

openapidocs/mk/v3/__init__.py

@@ -607,6 +607,19 @@ def get_parameters(self, operation) -> List[dict]:
 
         return results
 
+    def get_response_headers(self, response_definition: dict) -> dict:
+        """
+        Returns the headers of a response definition, resolving any $ref values
+        so that the template can access fields like schema and description directly.
+        """
+        headers = response_definition.get("headers")
+        if not headers:
+            return {}
+        return {
+            name: self._resolve_opt_ref(header_def)
+            for name, header_def in headers.items()
+        }
+
     def write(self) -> str:
         return self._writer.write(
             self.doc,

openapidocs/mk/v3/views_markdown/partial/request-responses.html

@@ -25,7 +25,7 @@
 {%- if definition.headers %}
 
 {% with rows = [[texts.name, texts.description, texts.schema]] %}
-{%- for header_name, header_definition in definition.headers.items() -%}
+{%- for header_name, header_definition in handler.get_response_headers(definition).items() -%}
 {%- set _ = rows.append([header_name, header_definition.description, header_definition.schema.type]) -%}
 {%- endfor -%}
 {{ rows | table }}

openapidocs/mk/v3/views_mkdocs/partial/request-responses.html

@@ -32,7 +32,7 @@
                 </tr>
             </thead>
             <tbody>
-                {%- for header_name, header_definition in definition.headers.items() %}
+                {%- for header_name, header_definition in handler.get_response_headers(definition).items() %}
                 <tr>
                     <td><code>{{header_name}}</code></td>
                     <td>{{header_definition.description}}</td>

tests/res/example9-openapi.yaml

@@ -0,0 +1,42 @@
+---
+openapi: 3.0.0
+info:
+  title: Header Ref Example
+  version: v1
+paths:
+  /pets:
+    get:
+      summary: List all pets
+      operationId: listPets
+      tags:
+        - Pets
+      responses:
+        "200":
+          description: A paged array of pets
+          headers:
+            Current-Page:
+              $ref: '#/components/headers/current-page'
+            X-Rate-Limit:
+              description: Rate limit per hour
+              schema:
+                type: integer
+          content:
+            application/json:
+              schema:
+                type: array
+                items:
+                  type: object
+                  properties:
+                    id:
+                      type: integer
+                    name:
+                      type: string
+components:
+  headers:
+    current-page:
+      description: The current page of total pages this response represents.
+      example: '1'
+      style: simple
+      schema:
+        type: string
+      required: true

tests/test_mk_v3.py

@@ -84,6 +84,22 @@ def test_swagger2_raises_not_supported():
         OpenAPIV3DocumentationHandler({"swagger": "2.0", "info": {}, "paths": {}})
 
 
+def test_v3_response_header_ref():
+    """
+    Regression test for https://github.com/Neoteroi/essentials-openapi/issues/60
+    Response headers that use $ref to #/components/headers/... should be resolved
+    without raising an UndefinedError.
+    """
+    data = get_file_yaml("example9-openapi.yaml")
+    handler = OpenAPIV3DocumentationHandler(data)
+    output = handler.write()
+
+    assert "Current-Page" in output
+    assert "The current page of total pages this response represents." in output
+    assert "X-Rate-Limit" in output
+    assert "Rate limit per hour" in output
+
+
 @pytest.mark.parametrize(
     "input,expected_result",
     [