Getting a type error when using an OpenAPI spec with a header that's missing schema.type

[benlei]

Describe the bug

I would get an error with the following message:

Cannot read properties of undefined (reading 'type') 

Here's how a part of my OpenAPI spec looks like:

          responses:
            '201':
              description: The resource was created successfully.
              headers:
                location:
                  description: URL of the created resource

With other generators it seems to be less strict.

Expected behavior

It'd be nice if there was a way to be less strict / default to string.

Current behavior

When running yarn docusaurus gen-api-docs all you get the following:

Cannot read properties of undefined (reading 'type') 

Possible solution

Make it less strict, or default to a string type if type property is undefined.

Context

Currently the Swagger docs for some projects are kind of hand written and aren't perfect - but the Swagger UI page for those projects still render just fine. It would be nice if the strictness could be toned down / default to string if type isn't present.

Your Environment

• Version used: v1.5.2

[welcome-to-palo-alto-networks]

🎉 Thanks for opening your first issue here! Welcome to the community!

[sserrata]

Hi @benlei, can you share a link to of copy of the full OpenAPI spec?

[benlei]

@sserrata Sure I created a repo: https://github.com/benlei/docusaurus-openapi-docs-failed-to-gen

Specifically added this from the template repo: https://github.com/benlei/docusaurus-openapi-docs-failed-to-gen/blob/master/examples/petstore.yaml#L857

And when I run yarn docusaurus gen-api-docs all I get:

[ERROR] TypeError: Cannot read properties of undefined (reading 'type')
    at /Users/blei/WebstormProjects/my-website-docu/node_modules/docusaurus-plugin-openapi-docs/lib/markdown/createStatusCodes.js:69:48
    at Array.map (<anonymous>)
    at /Users/blei/WebstormProjects/my-website-docu/node_modules/docusaurus-plugin-openapi-docs/lib/markdown/createStatusCodes.js:68:45
    at guard (/Users/blei/WebstormProjects/my-website-docu/node_modules/docusaurus-plugin-openapi-docs/lib/markdown/utils.js:21:26)
    at createResponseHeaders (/Users/blei/WebstormProjects/my-website-docu/node_modules/docusaurus-plugin-openapi-docs/lib/markdown/createStatusCodes.js:65:30)
    at /Users/blei/WebstormProjects/my-website-docu/node_modules/docusaurus-plugin-openapi-docs/lib/markdown/createStatusCodes.js:284:41
    at Array.map (<anonymous>)
    at createStatusCodes (/Users/blei/WebstormProjects/my-website-docu/node_modules/docusaurus-plugin-openapi-docs/lib/markdown/createStatusCodes.js:262:33)
    at createApiPageMD (/Users/blei/WebstormProjects/my-website-docu/node_modules/docusaurus-plugin-openapi-docs/lib/markdown/index.js:44:51)
    at /Users/blei/WebstormProjects/my-website-docu/node_modules/docusaurus-plugin-openapi-docs/lib/index.js:195:54

[sserrata]

For reference, it appears Redoc defaults to "any" when no schema is defined:

[sserrata]

Also note that spectral and other linters flag the missing schema or content definitions:

Since the missing schema in your example appears to violate the OpenAPI specification it's debatable as to whether it should be supported in our plugin.

[benlei]

I probably should setup a linter some time later... but besides that, It would be convenient for it to fallback, or at the very least have a more descriptive message about what what field/line/etc has the issue so that it can be quickly addressed.

[sserrata]

Hi @benlei, I agree the logging could be improved. It's on our roadmap to improve logging/error-handling.

I did a bit more research and came across this thread: OAI/OpenAPI-Specification#1657

After skimming through some of the responses/opinions, I think there's a strong case/consensus around interpreting no schema.type as "any" - or, basically leaving it up to the tooling to decide how to handle those cases.

[sserrata]

Available to test in 0.0.0-569