Redocly / Redocly/redoc

Support headers and contentType property from Encoding object

Open
#2,444 2 comments 1 reaction 0 assignees View on GitHub

Nobody has claimed this yet.

Type: Enhancement
Dominant language
TypeScript
Stars
25.9k
Forks
2.4k
Avg merge
13h 10m
Merged PRs (30d)
4

Description

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

Contributor guide

Open the contributing guide

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. Open a pull request that references the issue number.

Research direction

Start by tracing Redoc's request-body rendering for the supplied OpenAPI 3.1 multipart/form-data example, focusing on how Encoding objects are handled. Verify the UI against the example: each multipart part should show its contentType and defined headers, and the relevant header values should be editable where supported.

Written by the indexing model from the issue text.

Assessment

Tech stack
typescript
Domain
documentation, frontend
Issue type
Feature
Difficulty
4/5
Estimated time
3-5 days
Activity status
Stale
Clarity
Mostly clear
Newbie friendliness
38/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.