Currently, the @param tag in Rage::OpenAPI only supports documenting query parameters. However, when an endpoint accepts file uploads via multipart/form-data, there is no way to document these parameters using the existing tag.
The goal of this issue is to update the @param tag to support multipart/form-data parameters, so that file upload endpoints can be properly documented in the generated OpenAPI specification.
For example, given an endpoint like this:
class Api::V1::PhotosController < ApplicationController
# @param image {File} The photo to upload
# @param caption? {String} An optional caption for the photo
def create
end
end
The generated OpenAPI specification should include a multipart/form-data request body with the correct schema, e.g.:
requestBody:
content:
multipart/form-data:
schema:
type: object
properties:
image:
type: string
format: binary
caption:
type: string
required:
- image
@param and @request tags currently work.File (or a similar type) in the @param tag and generate a multipart/form-data request body instead of a query parameter.multipart/form-datafile -> {type: "string", format: "binary"}