OAS 3.0 Support Backlog

[shockey]

⚠️ Note to onlookers: don't rely on this information, this issue is out of date! We're breaking everything here out into their own issues soon.

This is a collection ticket for OAS3 specification features that are not yet supported by Swagger-UI.

Items that affect both UI and Client will be listed here as well, but Client-only items will be filed in the Client issue tracker.

Significant items should be broken out into their own ticket when work begins, but simple items can be addressed as a line item here.

Rendering

• Parameter example/examples is not displayed

#3616 is open for this.
Implement functionality for Try-It-Out simultaneously.

• Parameter style/explode is not displayed

• Parameter allowReserved is not displayed

• Parameter content is not displayed

Reuse method for displaying Request Bodies
Render all media types, even though only one is allowed by the specification

• Media type example/examples is not displayed

Identical to Request Body, Parameter content

• Callbacks are not rendered
• Media type encoding is not displayed

This has lots of moving parts before it's useful: breaking down jsonschema, rendering individual inputs, handling file uploads, etc

• Discriminator objects are not displayed

This will change the way we display allOf, anyOf, oneOf, not.

• Link-level servers are not displayed

Try-It-Out

• Parameter style/explode is not considered in request construction

Needs support in Swagger-Client, mostly. Important!

• Links can't be used to stage another operation
• Link-level servers are not available for executing requests
• Parameter content values are not rendered for Try-It-Out
• Parameter encoding values are not considered
• Blacklisted header names (Accept, Content-Type, Authorization) are not filtered out
• Path and operation-level servers are not available for executing requests
• Parameter allowEmptyValue is not considered in request value validation

Add a checkbox that allows construction of a request with that parameter empty (may require value validation changes)
if ‘send empty value’ is checked - you’re sending an empty value meaning the requirement is satisfied
Implementation may be best served by a split of Client's buildRequest based on definition version

• Security type openIdConnect is not supported
• Form Data:
  • Nested object serialization is not handled correctly (OAS 3.0 Form Data Try-It-Out object serialization #3788)
  • Form data fields should be displayed as items instead of a JSON object
  • File upload UI should appear when applicable

[shockey]

cc: @webron

[hkosova]

Also:

Rendering

• Display server description (implemented in UI v. 3.20.2 / Editor v. 3.6.17)
• Display server variable description
• Display the nullable attribute in schemas

Try It Out / Rendering

• Display enum as dropdown (implemented in UI v. 3.4.0 / Editor v. 3.1.12)
• UI to add/remove array items (implemented in UI v. 3.4.0 / Editor v. 3.1.12)
• Percent-encode query parameters with allowReserved=false (Query parameters with allowReserved=false not percent-encoded during OAS3 "Try It Out" #3817)

[zhandao]

enum not displayed as dropdowns

In the OAS3, enum is moved into schema, UI has not yet support this.

[leehicks]

Is there an update on when Authentication/Authorization will be supported by the UI? We used the "authorizations" in 2.0 heavily and are wanting to release with 3.0 support soon. This is a big missing piece for us. I saw mention in #3774, #3705, #3665 that it is being worked on in this issue number.