Supporting JSON schema type array in examples and rendering

[pietermees]

Opening this as an issue to document my findings. I might find time in the future to look at this and provide a PR, but not sure when that would happen.

Up until OpenAPI 3.0, nullable was an extension to JSON Schema.

Now that nullable is no longer valid in OpenAPI 3.1, the new proposed way to define a nullable field seems to be to use an array of values for the type.

Something like:

type:
  - string
  - "null"

This is aligned with the JSON Schema type spec. And is shown in the spec as an example.

I wasn't able to spend a lot of time on it yet, but it seems like this currently breaks the following code that is used to generate examples:

docusaurus-openapi-docs/packages/docusaurus-plugin-openapi-docs/src/openapi/createRequestExample.ts

Lines 217 to 227 in 61e4de7

	let fn = schema.default ? () => schema.default : primitives[type].default;
	if (format !== undefined) {
	fn = primitives[type][format] || fn;
	}
	if (fn) {
	return fn(schema);
	}
	return "Unknown Type: " + schema.type;

It would be relatively easy to resolve this issue by detecting the array there and defaulting to the first entry for example.

However, it seems like there is some code elsewhere that does the $ref folding into the schema object, which is stringifying the type value into something like "string,null", so it's not properly handling the array case. I'm not sure where this code is located.

Possibly here?

docusaurus-openapi-docs/packages/docusaurus-theme-openapi-docs/src/types.ts

Line 35 in fd92c40

type?: "string" | "number" | "integer" | "boolean" | "object" | "array";

We'd probably also need to update the nullable property rendering here to account for this new scenario?

docusaurus-openapi-docs/packages/docusaurus-theme-openapi-docs/src/theme/SchemaItem/index.tsx

Line 75 in fd92c40

nullable = schema.nullable;