$ref to #/components/headers does not resolve

[copiousfreetime]

I have a spec that uses components/headers and the path item responses reference them with $ref: '#/components/headers/.

Other openapi documentation tools parse this without failure, and this is valid in the spec.

Given a spec with snippets like the following:

# ... 
components:
  headers:
    current-page:
      description: The current page of total pages this response represents.
      example: '1'
      style: simple
      schema:
        type: string
      required: true
# ... 
paths:
  /pets:
    get:
      summary: List all pets
      operationId: listPets
      responses:
        "200":
          description: A paged array of pets
          headers:
            Current-Page:
              $ref: '#/components/headers/current-page'
# ... 

When running oad gen-docs -s ./openapi.yaml -d output.md the following error is observed:

jinja2.exceptions.UndefinedError: 'dict object' has no attribute 'schema'

The debugging I did resulted in finding that it blows up here:

https://github.com/Neoteroi/essentials-openapi/blob/e5fa8f260289c2d9c0058773d75a8c28da4123b1/openapidocs/mk/v3/views_mkdocs/partial/request-responses.html#L53

The header_definition has no schema. I think the $ref does not resolve. I did a test where I manually "resolved" the ref in another openapi spec (by just injecting it into the yaml) and it generated just fine.

I have created the start of a test in https://github.com/Neoteroi/essentials-openapi/compare/main...copiousfreetime:essentials-openapi:header-reference -- which errors out appropriately.

FAILED tests/test_mk_v3.py::test_v3_markdown_yaml_header_ref[example9] - jinja2.exceptions.UndefinedError: 'dict object' has no attribute 'schema'

At the moment I am not familiar enough with the codebase to fix this. But maybe this will be enough to point you in the right direction, maybe this is a straightforward fix?

Thanks!