OpenAPI 3.1 support has a bug w/ nullable types

[jasikpark]

Describe the bug

As mentioned in https://github.com/PaloAltoNetworks/docusaurus-openapi-docs/issues/410#issuecomment-2228526462, when using this plugin with an OpenAPI 3.1 schema that uses [string, null] as a list of valid types for a property, instead of showing the enum of types, it joins the array together with no spaces.

Expected behavior

Show a "nullable" tag for the property or just list the valid property types.

For example of the usage, see https://www.openapis.org/blog/2021/02/16/migrating-from-openapi-3-0-to-3-1-0 and "Swap nullable for type arrays"

Another example of this valid usage in OpenAPI 3.1: https://github.com/OAI/OpenAPI-Specification/issues/3148

Current behavior

The list of valid property types are joined into a string with no spaces.

Possible solution

Steps to reproduce

1. Create an OpenAPI 3.1 schema that has a property with type [string, null]
2. Render API docs with the plugin

Screenshots

Context

Trying to keep up-to-date with the current OpenAPI schema while providing clear, useful, and accurate api docs to our users.

Your Environment

• Version used:
• Environment name and version (e.g. Chrome 59, node.js 5.4, python 3.7.3): Safari 17.6
• Operating System and version (desktop or mobile): macOS 14.6.1
• Link to your project: https://docs.defined.net/api/defined-networking-api/

[sserrata]

Hi @jasikpark, not sure this is a bug given that 3.1 support is, officially, currently limited. That said, I think we can add support for this new syntax, i.e. type arrays.

[jasikpark]

That'd be great 💜

I guess my thought is presuming that the desire is to move towards better 3.1 support incrementally, therefore any issues with 3.1 support are bugs? Therefore this is a bug.

Another way to think is that "3.1 support is limited, so therefore any issues with the code are acceptable issues that aren't being prioritized right now", which I get but would be disappointed to hear about. And therefore this would be acceptable behavior and not a bug.

[MarcL01]

Fixed with https://github.com/PaloAltoNetworks/docusaurus-openapi-docs/pull/1017 - readme.com joins types with | which I copied here.

[robbieaverill]

#1017 is good, but we also need to add support for it in anyOf, allOf, oneOf, etc, as well in the type definitions.

OpenAPI 3.1 actually removes nullable (from 3.0) entirely - see https://www.openapis.org/blog/2021/02/16/migrating-from-openapi-3-0-to-3-1-0 -> "Swap nullable type for arrays". In terms of backwards compatibility in this library, supporting nullable for <= 3.0 schemas would be important.

[pietermees]

I realize I opened an issue that feels closely related to this. https://github.com/PaloAltoNetworks/docusaurus-openapi-docs/issues/1052

My issue was generated on 4.3.0, so still happens with #1017. If it would be preferred to fold it into this issue I'm happy to close it and move my notes here?