Redocly / Redocly/redoc

Support request samples for JSON parts in multipart/form-data requests

Open
#707 13 comments 9 reactions 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

We have an API with an endpoint that handles file uploads. The endpoint accepts multipart/form-data requests with two parts being a json content in the first part and binary file data in the second part.
We would like to give a request sample to the first (JSON) part.

We use openapi 3.0.0 spec, the request definition looks like this:

requestBody:
    required: true
    content:
        multipart/form-data:
            schema:
                type: object
                properties:
                    meta:
                        $ref: './meta.schema.json'
                    attachment:
                        type: string
                        format: binary
                        required: true
                required:
                - meta
                - attachment
            encoding:
                meta:
                    contentType: application/json; charset=utf-8

The meta schema contains an example, and it renders correctly if the request body is application/json.
Are we doing something wrong or ReDoc does not support our use case? Thanks!

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 reproducing the provided OpenAPI 3.0.0 multipart/form-data request in ReDoc and trace the request-body rendering path. Done means the JSON part's schema example is shown in the request sample while the binary attachment remains represented correctly.

Written by the indexing model from the issue text.

Assessment

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

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.