Schema is required in path parameter

[pbasista]

Q	A
Bug or feature request?	bug
Which Swagger/OpenAPI version?	3.0.1
Which Swagger-UI version?	3.13.3
How did you install Swagger-UI?	1. git clone [email protected]:swagger-api/swagger-ui.git 2. cd swagger-ui 3. npm install 4. copy custom specification files to dev-helpers/ 5. update dev-helpers/index.html 6. run npm run dev 7. open browser at http://0.0.0.0:3200/
Which browser & version?	not relevant
Which operating system?	not relevant

Demonstration API definition

openapi: "3.0.1"
info:
  title: Test of schema requirement in path parameter
  version: "0.1"
paths:
  /foo/{bar}:
    parameters:
      - name: bar
        in: path
        required: true
    get:
      responses:
        "200":
          description: ok response

Configuration (browser query string, constructor, config.yaml)

This line:

swagger-ui/dev-helpers/index.html

Line 46 in dc7d705

url: "http://petstore.swagger.io/v2/swagger.json",

has been changed to this:

url: "example.openapi.yaml",

The specification file example.openapi.yaml was copied to dev-helpers/ directory. No other changes.

Expected Behavior

When the foo/{bar} path is expanded, it is displayed properly with its parameter.

Current Behavior

When the foo/{bar} path is expanded, the path parameter is not displayed. Instead, a message saying "😱 Could not render ParameterRow, see the console." is shown. The console shows that TypeError: "schema is undefined" occurred on this line:

swagger-ui/src/core/components/parameter-row.jsx

Line 111 in dc7d705

let type = schema.get("type")

Possible Solution

If I am reading the OpenAPI v3 specification correctly, the schema field is not required for path parameter objects. Yet, swagger-ui requires it.

When a simple schema like this:

schema:
  type: integer

is added to the path parameter object, swagger-ui displays the path correctly, including the parameter.

I believe the requirement of the schema field in path parameter objects violates the specification and therefore needs to be removed.

Context

The online Swagger Editor also shows a similar error message for the above mentioned API definition:

Schema error at paths['/foo/{bar}'].parameters[0]
should have required property 'schema'
missingProperty: schema

If the issue proves to be the non-compliance with the specification, I believe it should be fixed there as well.

[shockey]

Hi @pbasista!

The schema property is indeed required, but it's definitely hidden pretty well in the Parameter Object section (it lacks the usual REQUIRED marker):

The rules for serialization of the parameter are specified in one of two ways. For simpler scenarios, a schema and style can describe the structure and syntax of the parameter.

....

For more complex scenarios, the content property can define the media type and schema of the parameter. A parameter MUST contain either a schema property, or a content property, but not both.

In fact, I only picked up on this on my third read of the spec 😄

Consider raising this as a user experience issue over with the OAI: https://github.com/OAI/OpenAPI-Specification

[pbasista]

Thanks @shockey. I have also missed that part of the specification. This issue is invalid then.

An issue about difficult-to-notice requirement of one of those fields in the specification has been raised here:
OAI/OpenAPI-Specification#1542

[lock]

Locking due to inactivity.

This is done to avoid resurrecting old issues and bumping long threads with new, possibly unrelated content.

If you think you're experiencing something similar to what you've found here: please open a new issue, follow the template, and reference this issue in your report.

Thanks!