'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.