swagger-api / swagger-api/swagger-ui

Request body descriptions are not shown when the input type is a file upload

Open
#5,637 3 comments 2 reactions 1 assignee View on GitHub

@shaman-004 is already working on this.

Since Nov 3, 2025.

Hacktoberfest P3 specification: 3.x type: bug
Dominant language
JavaScript
Stars
29k
Forks
9.3k
Avg merge
2d 23h
Merged PRs (30d)
25

Description

Q&A (please complete the following information)
  • Swagger-UI version: 3.23.11
  • Swagger/OpenAPI version: OpenAPI 3.0
Content & configuration
        "requestBody": {
          "description": "A zip file containing files that will be unzipped",
          "content": {
            "application/octet-stream": {
              "schema": {
                "type": "string",
                "format": "binary",
                "nullable": true
              }
            }
          },
          "required": true
        }
Describe the bug you're encountering

When a request body is a type that causes the UI to use an input type=file box, then the description is not shown, and instead a message about examples is shown (even if no examples are specified in the openapi json). The message is:

Example values are not available for application/octet-stream media types.

Changing the type to something like text/plain results in the description being shown.

Expected behavior

The description should be shown above the file input box. The warning about examples shouldn't be shown if none are specified.

Additional context or thoughts

Maybe there should be support for per-content-type descriptions (e.g. via the schema's title attribute) so you can explain the differences between different upload types.

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.

Assessment

This issue has not been assessed yet.

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.