Redocly / redoc

📘 OpenAPI/Swagger-generated API Reference Documentation
https://redocly.github.io/redoc/
MIT License
23.44k stars 2.29k forks source link

Support headers and contentType property from Encoding object #2444

Open jeremyfiel opened 11 months ago

jeremyfiel commented 11 months ago

Describe the problem to be solved Encoding object contains a headers map which should be content editable in the redoc UI to modify the header values required for the multipart/form-data request, particularly the ability to add the boundary and filename parameters in the header value. I don't have a premium subscription, so unable to view the try-it out functionality. I'm not sure if this is fully supported.

More importantly, the parts of the multipart body are not visually defined in the UI based on the contentType property defined in encoding, nor can the user view the defined headers for each body part.

form-data is a very common web-based http api functionality and the OpenAPI specification provides sufficient capability to define these apis. Redoc is lacking the ability for users to view the full description of these apis

openapi: 3.1.0
info:
  title: an api
  version: 1.0.0
servers:
  - url: https://api.thing.com/api/v1
paths:
  /thing:
    post:
      summary: a request body with encoding defined per the OAS specification
      requestBody:
        description: a multpart request body with an encoding object
        content:
          multipart/form-data:
            schema:
              type: object
              properties:
                metadata:
                  $schema: "https://json-schema.org/draft/2020-12/schema"
                  title: "An encoding object schema defined as application/json"
                  type: object
                  properties:
                    key1:
                      type: string
                    key2:
                      type: number
                  required:
                    - key1
                    - key2
                file:
                  type: string
                  format: binary
            encoding:
              metadata:

                contentType: application/json
              file:
                headers:
                  content-disposition:
                    $ref: '#/components/headers/content-disposition'
                contentType: application/octet-stream
            examples:
              formdata_request_body:
                $ref: "#/components/examples/formdata-request"
      responses: 
        '201':
          description: Created
          content:
            application/json:
              schema: 
                type: string
components:
  headers:

    content-disposition:
      description: Describes the file name of an entity-body
      schema:
        type: string
      required: true
  examples:
    formdata-request:
      summary: an example form-data request body
      externalValue: "./examples/formdata-request.txt"
#example file
POST "https://api.thing.com/api/v1/thing" HTTP/1.1
Authorization: ''
Content-Type: multipart/form-data; boundary=----WebKitFormBoundary7MA4YWxkTrZu0gW

----WebKitFormBoundary7MA4YWxkTrZu0gW
Content-Disposition: form-data; name='file'; filename:"formdata-request.txt"
Content-Type: application/octet-stream
Content-Length: <number>

<test_file data in bytes>

----WebKitFormBoundary7MA4YWxkTrZu0gW
Content-Disposition: form-data; name='metadata'
Content-Type: application/json
Content-Length: <number>

{
    "key1": "<filename>",
    "key2": 1
}
----WebKitFormBoundary7MA4YWxkTrZu0gW--

Describe the solution you'd like

Describe alternatives you've considered none

Additional context image

Orest-Yastremskyy commented 10 months ago

Hi @jeremyfiel

Thank you for taking the time to share this idea with us.

I have added it to our list of ideas so that our Product Team can evaluate how it fits our roadmap.