Support headers and contentType property from Encoding object
Nobody has claimed this yet.
- 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
Contributor guide
First steps
- Read the whole issue, then the project's contributing guide.
- Comment on the issue to say you are picking it up — it saves two people doing the same work.
- Fork the repository and make your change on a branch.
- 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