Swagger-ui: 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
• [x] 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

• [x] 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:
  
  
  
  • [x] Nested object serialization is not handled correctly (#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

• [x] 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

• [x] Display enum as dropdown (implemented in UI v. 3.4.0 / Editor v. 3.1.12)
• [x] UI to add/remove array items (implemented in UI v. 3.4.0 / Editor v. 3.1.12)
• [x] Percent-encode query parameters with allowReserved=false (#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 https://github.com/swagger-api/swagger-ui/commit/d587d9c9ea794ea2a5afb59f583c3ed40c6321b6 was regressed at some point between 3.3.1 and 3.4.4. ( Callbacks are not rendered )

[webron]

@craigjbass thanks, see https://github.com/swagger-api/swagger-editor/issues/1565.

[amarel123]

File upload UI should appear when applicable

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

[rsidon]

Hi,
I am also interested in the status of File Upload UI (amarel123's question).
We really need this file chooser for our swagger playground.
Is there any update about the status of this issue?
10x

[shockey]

Some updates:

• anyOf / oneOf examples: Come up with solution-ish, or document to say its not something we're going to fix was removed in favor of being tracked in #3803 and #2651.
• Path and operation-level servers are not displayed was removed since it was tracked in #3820 and implemented in #3972.

Besides that, all checkbox statuses have been updated.

If a task is still unchecked... no update for now 😄 if you're here to ask for a specific thing to get done, check to see if anyone has mentioned it, and if so 👍 their comment. If no one has mentioned it, feel free to comment about it.

We'll do our best to address things here in order of demand (I see you, File Upload folks!)

[nishantgupta91-zz]

Hi,
What's the status of "Server description is not displayed"? I also need this. Moreover, the feature with multiple examples doesn't work. @shockey Can you please confirm if the functionality mentioned here "https://swagger.io/docs/specification/adding-examples/" actually works? Thanks

[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!

[iwt-nduesing]

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" ] }