Quick answer: A generated multipart builder takes your plain fields and file inputs and assembles them into a correctly formatted multipart/form-data body, with a boundary, the per-part Content-Disposition headers, and the matching request Content-Type. The generator handles the wire format so you do not hand-build it. You still provide the file streams, decide whether to stream large uploads, and verify the body the server actually receives.
What the builder assembles
A multipart body is a sequence of parts separated by a boundary string. Each field part carries a name in its Content-Disposition header, and each file part adds a filename and often its own Content-Type. The builder picks a boundary that does not collide with the payload, joins the parts with the required CRLF line endings, and sets the request Content-Type to include that same boundary. The calling code works with named fields and file handles rather than raw bytes.
Why not hand-build it
Concatenating the body as a string looks simple but breaks in quiet ways. A boundary value can appear inside binary file content, line endings have to be exact CRLF, and binary data is not safe to treat as text. The generated builder and the underlying HTTP library already solve these problems, including binary-safe encoding, so hand-building mostly reintroduces bugs the tooling removed.
urlencoded versus multipart
The two form encodings are not interchangeable.
| Aspect | x-www-form-urlencoded | multipart/form-data |
|---|---|---|
| Best for | Simple key-value fields | Fields plus files or binary |
| Body | One encoded string | Boundary-separated parts |
| File upload | No | Yes |
| Overhead | Small | Larger per-part headers |
Pick multipart when the operation includes a file, and let the builder set the Content-Type; manually setting a multipart Content-Type without the boundary leaves the server unable to parse the parts.
Streaming large files
Reading a large upload fully into memory wastes memory and can fail on big files. The builder should accept a stream or file handle and pipe it into the part as it sends, so the file is read in chunks rather than buffered whole. Small text fields can still be passed directly, but file parts should default to a stream when the size is unknown.
Verifying the body
A client that builds without error has not yet proved the server accepts the shape. Send the request against a local mock that records the incoming body, or run an ordered scenario against the real endpoint and assert the field names, filename, and status; Powerduck can capture the recorded request so you can confirm the boundary and parts match the spec before you rely on the upload.
Repeated fields and multiple files
Real forms often go beyond one field and one file. A single field name can repeat to send a list, and one file field can accept several files. The builder emits one part per value, each carrying the same field name, and the order of those parts follows the order you pass them in. Whether the server reads repeated names as an array depends on the server, and generators differ in how they name repeated parts, so a spec that uses arrays or multi-file uploads deserves a real check that the part order and names match what the endpoint expects.
Honest limits
The generator follows the spec, and when the spec is vague about binary encoding, filenames, or repeated fields, the output has to be checked rather than assumed. Languages and libraries encode arrays, multiple files, and nested objects differently, so the builder guarantees only what the spec states clearly. It also does not read files from disk for you, check permissions, or handle a server that rejects the type or size; a well-formed client request is the start, not proof the upload succeeds.
Frequently asked questions
Should I set the Content-Type myself? No. Let the builder set it with the boundary, or the server cannot parse the parts.
Can multipart send simple text fields? Yes, but plain key-value forms are better as urlencoded when there is no file.
How are large files handled? Pass a stream so the part is sent in chunks instead of buffering the whole file.
Does a correct build mean the upload works? No. Verify against a mock or the real endpoint, including size and type rules.
The bottom line
A generated multipart builder turns named fields and file streams into a boundary-separated, binary-safe body with the correct headers, which is why hand-building it is a mistake. Stream large files and verify the received body. For more on generated clients, see the OpenAPI codegen guide hub.

