OAI / OAI/OpenAPI-Specification

How to state parameter requirements in HTTP headers?

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

Nobody has claimed this yet.

headers media and encoding
Dominant language
Markdown
Stars
31.2k
Forks
9.2k
Avg merge
6h 37m
Merged PRs (30d)
27

Description

For example, as described in the guide, in a request such as

POST /upload HTTP/1.1
Content-Length: 428
Content-Type: multipart/form-data; boundary=abcde12345
--abcde12345
Content-Disposition: form-data; name="profileImage"; filename="image1.png"
Content-Type: application/octet-stream
{…file content…}
--abcde12345--

how would a spec state that the filename parameter in header Content-Disposition is required and explain special usage in a description?
RFCs state that the filename parameter is optional.
It's not clear how to express parameters for a header object.

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 with the linked multipart request guide and the OpenAPI Header Object definition, then compare the question with RFC 7578's treatment of the filename parameter. Determine whether the specification can express this requirement and description, and document the agreed syntax or limitation with a representative example.

Written by the indexing model from the issue text.

Assessment

Tech stack
openapi
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.