'str' object has no attribute 'get'

[StarfallProjects]

Have set up neoteroi.mkdocsoad, but when running mkdocs serve, am getting:

ERROR    -  Error reading page 'api\api-reference-3.md': 'str' object has no attribute 'get'
Traceback (most recent call last):
  File "C:\Users\debor\AppData\Local\Programs\Python\Python310\lib\runpy.py", line 196, in _run_module_as_main       
    return _run_code(code, main_globals, None,
  File "C:\Users\debor\AppData\Local\Programs\Python\Python310\lib\runpy.py", line 86, in _run_code
    exec(code, run_globals)
  File "C:\Users\debor\Desktop\docs\n8n-docs\venv\Scripts\mkdocs.exe\__main__.py", line 7, in <module>
  File "C:\Users\debor\Desktop\docs\n8n-docs\venv\lib\site-packages\click\core.py", line 1128, in __call__
    return self.main(*args, **kwargs)
  File "C:\Users\debor\Desktop\docs\n8n-docs\venv\lib\site-packages\click\core.py", line 1053, in main
    rv = self.invoke(ctx)
  File "C:\Users\debor\Desktop\docs\n8n-docs\venv\lib\site-packages\click\core.py", line 1659, in invoke
    return _process_result(sub_ctx.command.invoke(sub_ctx))
  File "C:\Users\debor\Desktop\docs\n8n-docs\venv\lib\site-packages\click\core.py", line 1395, in invoke
    return ctx.invoke(self.callback, **ctx.params)
  File "C:\Users\debor\Desktop\docs\n8n-docs\venv\lib\site-packages\click\core.py", line 754, in invoke
    return __callback(*args, **kwargs)
  File "C:\Users\debor\Desktop\docs\n8n-docs\venv\lib\site-packages\mkdocs\__main__.py", line 181, in serve_command  
    serve.serve(dev_addr=dev_addr, livereload=livereload, watch=watch, **kwargs)
  File "C:\Users\debor\Desktop\docs\n8n-docs\venv\lib\site-packages\mkdocs\commands\serve.py", line 63, in serve     
    config = builder()
  File "C:\Users\debor\Desktop\docs\n8n-docs\venv\lib\site-packages\mkdocs\commands\serve.py", line 58, in builder   
    build(config, live_server=live_server, dirty=dirty)
  File "C:\Users\debor\Desktop\docs\n8n-docs\venv\lib\site-packages\mkdocs\commands\build.py", line 292, in build    
    _populate_page(file.page, config, files, dirty)
  File "C:\Users\debor\Desktop\docs\n8n-docs\venv\lib\site-packages\mkdocs\commands\build.py", line 170, in _populate_page
    page.markdown = config['plugins'].run_event(
  File "C:\Users\debor\Desktop\docs\n8n-docs\venv\lib\site-packages\mkdocs\plugins.py", line 102, in run_event       
    result = method(item, **kwargs)
  File "C:\Users\debor\Desktop\docs\n8n-docs\venv\lib\site-packages\neoteroi\mkdocsoad\__init__.py", line 42, in on_page_markdown
    return self.rx.sub(self._replacer, markdown)
  File "C:\Users\debor\Desktop\docs\n8n-docs\venv\lib\site-packages\neoteroi\mkdocsoad\__init__.py", line 32, in _replacer
    return handler.write(data)
  File "C:\Users\debor\Desktop\docs\n8n-docs\venv\lib\site-packages\openapidocs\mk\v3\__init__.py", line 327, in write
    data, operations=self.get_operations(), texts=self.texts, handler=self
  File "C:\Users\debor\Desktop\docs\n8n-docs\venv\lib\site-packages\openapidocs\mk\v3\__init__.py", line 92, in get_operations
    tag = self.get_tag(path_item) or ""
  File "C:\Users\debor\Desktop\docs\n8n-docs\venv\lib\site-packages\openapidocs\mk\v3\__init__.py", line 122, in get_tag
    tags = operation.get("tags")
AttributeError: 'str' object has no attribute 'get'

[RobertoPrevato]

Thank You for reporting this issue. Could you please share some details about your specification file? I am asking because that portion of code is trying to read the tags of an Operation object (reference), which should not be a string.

More information would help me understanding the circumstances for this error to happen.

[StarfallProjects]

Sure! The draft PR is here: https://github.com/n8n-io/n8n-docs/pull/818 Thanks for looking at it!

[RobertoPrevato]

Thank You @StarfallProjects, now I understand the case! It's about a feature that is currently missing in essentials-openapi, that is support for OpenAPI Specification files split among multiple files (ref.).

I'm willing to add this feature, it shouldn't be much work. PS. I am slow when replying during the day because I cannot reply here while at work.

[RobertoPrevato]

I started working on this new feature, but I need a bit more time to complete it, in the worst case I should be able to publish it in the weekend.

[StarfallProjects]

Ah amazing! Looking forward to seeing it :-)

[RobertoPrevato]

Hi! I share a preview of the work in progress:

• support for splitting OAD specification files into multiple files is already implemented

However, I noticed more improvements that can be done to better satisfy your use case.

The most complex detail is this one: you are using $ref to external files when describing properties like this (e.g. in WorkflowInformation.yml):

  nodes:
    type: array
    items:
      $ref: './NodeInformation.yml'

For such cases, it would be best if the tool that generates markdown code from OAD files was able to configure automatically entries to the components section (or reuse existing $refs), so that NodeInformation can be described once and linked (meaning configured automatically as '#/components/schemas/NodeInformation').

The alternative would require an action on your side, meaning for example, to edit your file WorkflowInformation.yml to replace $ref: './NodeInformation.yml' with $ref: '#/components/schemas/NodeInformation'. This would make sense anyway since you are also specifying the NodeInformation entity $ref: './NodeInformation.yml' inside ./schemas/_index.yml.

By the way, this is very interesting for me because it's the first time I interact with a technical writer about OpenAPI Documentation - I always spoke about these with programmers who want their documentation to be generated automatically by some tool (I often had a different point of view compared to my colleagues, because I see the value of hand-written technical documentation).

[RobertoPrevato]

~~I'll take care of those details, anyway, it doesn't take much time - so you don't need to change your references.~~

[UPDATE] after looking into the topic, there are too many complications handling automatic replacements of $ref links going always to files instead of #/components/schemas/….

I will release a new version of mkdocs-plugins and essentials-openapi to add support for resolving file references, but it won't include that additional optimization.

In other words, the proper way should be to use $ref links as you are doing in ./schemas/_index.yml, but then not reference the same files in Object and Array schemas - instead reference #/components/schemas/… for those.

[RobertoPrevato]

Hi @StarfallProjects I just published two updates.

Can you please try again after upgrading these dependencies:

pip install -U neoteroi-mkdocs essentials-openapi

Please also read my previous messages, to reuse the schema definitions from your components section instead of linking the files.

[StarfallProjects]

@RobertoPrevato picking up these messages this morning - thanks so much for the detailed guidance. I'll feed back to our devs about the $ref format.

[dborchers-gc]

I've got the same Error by importing the msgraph-api.yaml from this URL: https://raw.githubusercontent.com/microsoftgraph/msgraph-metadata/refs/heads/master/openapi/v1.0/openapi.yaml Same eror when downloading and importing local.

Here are the Logs:

ERROR   -  Error reading page 'hilfe/graphapi/openapi_msgraphv1.md': 'str' object has no attribute 'get'
Traceback (most recent call last):
  File "/opt/hostedtoolcache/Python/3.13.2/x64/bin/mkdocs", line 8, in <module>
    sys.exit(cli())
             ~~~^^
  File "/opt/hostedtoolcache/Python/3.13.2/x64/lib/python3.13/site-packages/click/core.py", line 1161, in __call__
    return self.main(*args, **kwargs)
           ~~~~~~~~~^^^^^^^^^^^^^^^^^
  File "/opt/hostedtoolcache/Python/3.13.2/x64/lib/python3.13/site-packages/click/core.py", line 1082, in main
    rv = self.invoke(ctx)
  File "/opt/hostedtoolcache/Python/3.13.2/x64/lib/python3.13/site-packages/click/core.py", line 1697, in invoke
    return _process_result(sub_ctx.command.invoke(sub_ctx))
                           ~~~~~~~~~~~~~~~~~~~~~~^^^^^^^^^
  File "/opt/hostedtoolcache/Python/3.13.2/x64/lib/python3.13/site-packages/click/core.py", line 1443, in invoke
    return ctx.invoke(self.callback, **ctx.params)
           ~~~~~~~~~~^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
  File "/opt/hostedtoolcache/Python/3.13.2/x64/lib/python3.13/site-packages/click/core.py", line 788, in invoke
    return __callback(*args, **kwargs)
  File "/opt/hostedtoolcache/Python/3.13.2/x64/lib/python3.13/site-packages/mkdocs/__main__.py", line 288, in build_command
    build.build(cfg, dirty=not clean)
    ~~~~~~~~~~~^^^^^^^^^^^^^^^^^^^^^^
  File "/opt/hostedtoolcache/Python/3.13.2/x64/lib/python3.13/site-packages/mkdocs/commands/build.py", line 310, in build
    _populate_page(file.page, config, files, dirty)
    ~~~~~~~~~~~~~~^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
  File "/opt/hostedtoolcache/Python/3.13.2/x64/lib/python3.13/site-packages/mkdocs/commands/build.py", line 163, in _populate_page
    page.markdown = config.plugins.on_page_markdown(
                    ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~^
        page.markdown, page=page, config=config, files=files
        ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
    )
    ^
  File "/opt/hostedtoolcache/Python/3.13.2/x64/lib/python3.13/site-packages/mkdocs/plugins.py", line 635, in on_page_markdown
    return self.run_event('page_markdown', markdown, page=page, config=config, files=files)
           ~~~~~~~~~~~~~~^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
  File "/opt/hostedtoolcache/Python/3.13.2/x64/lib/python3.13/site-packages/mkdocs/plugins.py", line 566, in run_event
    result = method(item, **kwargs)
  File "/opt/hostedtoolcache/Python/3.13.2/x64/lib/python3.13/site-packages/neoteroi/mkdocs/oad/__init__.py", line 45, in on_page_markdown
    return self.rx.sub(self._replacer, markdown)
           ~~~~~~~~~~~^^^^^^^^^^^^^^^^^^^^^^^^^^
  File "/opt/hostedtoolcache/Python/3.13.2/x64/lib/python3.13/site-packages/neoteroi/mkdocs/oad/__init__.py", line 35, in _replacer
    return handler.write()
           ~~~~~~~~~~~~~^^
  File "/opt/hostedtoolcache/Python/3.13.2/x64/lib/python3.13/site-packages/openapidocs/mk/v3/__init__.py", line 427, in write
    operations=self.get_operations(),

Maybe you have another idea @RobertoPrevato?

[RobertoPrevato]

Hi @dborchers-gc I checked, and the error in the library is that it does not support summary and description properties of the path object. There is a function that tries to obtain tags from each property inside a path object, and it incorrectly assumes all child properties are of operation type. The fix to the bug is relatively simple: ignore the str properties; but maybe something more should be done with summary and description for the path objects,

[RobertoPrevato]

There is the same issue with servers and parameters https://swagger.io/specification/.

[dborchers-gc]

thanks @RobertoPrevato is there something i can do now or do i have to wait for your fix in the plugin?

[dborchers-gc]

But another question. Ive also implemented this example: https://raw.githubusercontent.com/mitquinn/sharepoint-openapi/refs/heads/master/sharepoint-openapi.yaml

It also have summary and description in it and it works fine. Your answer looks like teh properties summary and description are the main problems, or didnt i understand you right?

[RobertoPrevato]

@dborchers-gc I can handle it, I already started working on it. The problem is about summary and description on path items, not operations. I know for certain because I debugged with your first YAML and exceptions are happening for that reason. Like in this example of your first specification file:

  /dataPolicyOperations:
    description: Provides operations to manage the collection of dataPolicyOperation entities. # <---
    get:
      tags:

I am fixing the issue and also handling properly the possible parameters defined at path item level instead of operation item level.

[RobertoPrevato]

@dborchers-gc please try pip install essentials-openapi==1.1.1.

I could generate markdown and mkdocs output from your example https://raw.githubusercontent.com/microsoftgraph/msgraph-metadata/refs/heads/master/openapi/v1.0/openapi.yaml.