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.

[webron]

Yup. The authorization should be included by in this week's release. Keep in mind it's more about compatibility with what existed in 2.0 (base auth, oauth2, and api key). That means that OIDC is not going to be available yet. As for bearer (JWT!), that might be in, but @shockey would be able to verify.

[shockey]

type: http
scheme: bearer

will be supported 😄

[webron]

O.M.G. !!!! !! ! 😱

[shockey]

@leehicks, FYI, support for most 3.0 security schemes were added in tonight's release! Check out the release notes for more info.

[webron]

@leehicks - release notes - https://github.com/swagger-api/swagger-ui/releases/tag/v3.4.0

If you encountered an issue with the implementation, please file a ticket, providing the requested details in the template.

[csvikram]

@webron - Any progress on below issues?

1. Form data fields should be displayed as items instead of a JSON object.
2. File upload UI should appear when applicable

[webron]

We try to keep the list above up to date...

[craigjbass]

Hey - looks like d587d9c was regressed at some point between 3.3.1 and 3.4.4. ( Callbacks are not rendered )

[webron]

@craigjbass thanks, see swagger-api/swagger-editor#1565.

[konradziczek]

File upload UI should appear when applicable

What is the current progress? It's very useful option.

[Fannon]

Also needing the file upload back in OpenApi 3.0 :) Is there a dedicated issue to watch?

Thank you for working on it!

[jelanwar]

Hi,
Is there any updated regarding Parameter example/examples is not displayed? as it is very useful option to have

[jonyeezs]

File upload UI should appear when applicable

Is there anything we can help speeding this up?

[webron]

@jonyeezs PRs help ;)

[heldersepu]

@webron the comment from @jelanwar got me thinking, "anything" ...
maybe this is an opportunity to monetize Open Source projects?

What if people interested in speeding features/bug fixes could put a coin bounty on the issues?
That should bring developers to submit PR to collect the bounty

[akalongman]

We really need the feature described in #4345

[imsopov]

Please allow this soon!

[zeromake]

doc
in is header support

api_key:
    type: "apiKey"
    name: "api_key"
    in: "header"

in is cookie not support has error

api_key:
    type: "apiKey"
    name: "api_key"
    in: "cookie"

error:

Schema error at securityDefinitions['api_key'].in
should be equal to one of the allowed values
allowedValues: header, query

[hkosova]

@zeromake make sure your spec is openapi: 3.0.0 and not swagger: '2.0'.

[malutanpetronel]

..
* @OA\MediaType(
* mediaType="multipart/form-data",
* @OA\Schema(
* type="object",
* @OA\Property(
* property="files",
* description="Choose a file to upload",
* type="array",
* @OA\Items(
* description="file",
* type="string",
* format="binary",
* ),
...
after this I use
public function upload(Request $request)
{
//$imageContent = $request->getContent();
$files = $request->input('files');
$files = explode(',', $files);
foreach ($files as $file) {
dd($file);
}
}

and get
..characters">[object File]"...

How I am suppose to play with the [object File] above to finish the upload please ?

[lcahlander]

When is multipart file upload going to be supported. You had this before!

[nicod-pc]

When is multipart file upload going to be supported. You had this before!

It is supported in 2.9.2.

[lcahlander]

When is multipart file upload going to be supported. You had this before!

It is supported in 2.9.2.

It is not showing up for me. Please see my stackoverflow https://stackoverflow.com/questions/54334438/how-do-i-specify-a-multifile-upload-in-openapi

[lcahlander]

When is multipart file upload going to be supported. You had this before!

It is supported in 2.9.2.

It is not showing up for me. Please see my stackoverflow https://stackoverflow.com/questions/54334438/how-do-i-specify-a-multifile-upload-in-openapi

The picker shows up, but the UI does not appear to send the filename or mime type along with the binary.

[hkosova]

@lcahlander

The picker shows up, but the UI does not appear to send the filename or mime type along with the binary.

This is issue #4600.

[beltschatsar]

Hi,

Can we have status about this missing feature ?

Try-it-out

• Links can't be used to stage another operation

So that an api call output can serve as input for another call (as explained there: https://swagger.io/docs/specification/links/)

Thanks!

[j-ibarra]

Hi there; I am trying to send multiple files in one property, as described in the Specification, I declare

 /testmultipart:
    post:
      summary: Send multipart request.
      requestBody:
        content:
          multipart/form-data:
            schema:
              properties:
              # The property name 'file' will be used for all files.
                file:
                  type: array
                  items:
                    type: string
                    format: binary

when I send the request I spect

curl -X POST -H "Content-Type: multipart/form-data" "http://localhost:3000/testmultipart" --form '[email protected]' --form '[email protected]' --form '[email protected]' '

but I see this in the body

{ "file": [ "string" ] }

[silkfire]

What's the status of

• Links can't be used to stage another operation

and rendering links as hyperlinks?