search

Apipie / apipie-rails

Ruby on Rails API documentation tool
Apache License 2.0
2.47k stars 459 forks source link

How to specify binary-type params #878

Open natotthomer opened 1 year ago

natotthomer commented 1 year ago

I have a POST request that I'm documenting that accepts a number of parameters, including one called images which is an array of binary files (image files). If I was documenting a param that's an array of a basic type, I'd write something like param :abc, Array, of: String, desc: "abc param description", required: true. I'm not even sure how to annotate a binary on its own let alone an array of binaries.

TLDR: How does one annotate binaries as an incoming param to a POST or PATCH request?

mathieujobin commented 1 year ago

Do you have a ruby class that you could specify there? like Image or something?

natotthomer commented 1 year ago

Hmmm, that's a thought. But it's coming in as a binary string, I would not think that would map well onto the Image class. It's just a pure blob. Eventually those objects get saved in the DB as ActiveRecord attachments.

mathieujobin commented 1 year ago

it's a "pure blob" but it's still transferred via HTTP as a string, I still think it should be defined as a ruby class not in the API gem. Say it's a JPEG blog, then you create IncomingJpegBlob or something that would digest it.

I'm sorry, I can't think of anything else.