Swagger UI's display of multiple-typed attributes is confusing

Q&A (please complete the following information)

• OS: OS X
• Browser: Firefox Developer Edition
• Version: 63.0b14
• Method of installation: dist assets
• Swagger-UI version: 3.19.3
• Swagger/OpenAPI version: OpenAPI 3.0

Content & configuration

Example Swagger/OpenAPI definition:

openapi: '3.0.0'
info:
  title: Foo API
  version: '0.1.0'
components:
  schemas:
    FooType:
      type: ['null', 'string', 'number']

(The important part is the JSON Schema type field being a list.

Swagger-UI configuration options: We use the defaults in the dist assets, except we set validatorUrl to null.

Describe the bug you’re encountering

The output is confusing. This is how the above JSONSchema will be rendered by Swagger UI:

Some whitespace between the different possible types, perhaps a , , or some indication that it must be one of those types, would greatly clarify what is happening.

[shockey]

@thanatos:

I suppose there’s nothing actionable here, then, since I was under the apparently false impression that OpenAPI was incorporating JSONSchema for validation.

OpenAPI does incorporate JSON Schema, but there are limits, which the specification covers in detail (emphasis mine):

The Schema Object allows the definition of input and output data types. These types can be objects, but also primitives and arrays. This object is an extended subset of the JSON Schema Specification Wright Draft 00.

Additional properties defined by the JSON Schema specification that are not mentioned here are strictly unsupported.

https://github.com/OAI/OpenAPI-Specification/blob/master/versions/3.0.0.md#schema-object

---

it would be extremely helpful if Swagger UI itself validated OpenAPI

Thanks for the feedback 😄

We’ve made the decision to keep validation in Swagger Editor, since the UI is commonly used by folks that can’t edit the document (think of a company using Swagger UI to host their documentation… if I’m using their API and there’s a bug in their document, why should I get a validation error about it?), while the Editor is almost always used by someone that has the power to fix any errors that crop up.

[shockey]

Closing due to inactivity.

This is simply to keep our issue tracker clean - feel free to comment if there are any further thoughts or concerns, and we’ll be happy to reopen this issue.