Documenting multipart/form-data file format


#1

Hi I am trying to document the format of a file that can be uploaded through multipart/form-data POST, but it it seems this is not possible… did I miss something?

Ideally I would like to have something like:

body:
  multipart/form-data:
    formParameters:
      file:
        description: The file to be uploaded
        required: true
        type: file
          application/json:
            schema: json.schema.ref
            example: !include example.json
          application/xml:
            schema: xml.schema.ref
            example: !include example.xml

Thoughts?


#2

Hi @egiraudy you are correct, we don’t provide the ability to explicitly/formally document the format of a file that can be uploaded through multipart/form-data in the way you’ve described above. You can provide a single example, like this:

body:
  multipart/form-data:
    formParameters:
      file:
        description: The file to be uploaded
        required: true
        type: file
        example: !include example.json

But we do not support schemas for uploaded files, or differentiation on media/filetype.

One option would be to expand the description of the parameter to include the documentation desired, or to link to the schemas/examples for the uploaded file types on an external server from within that description.

@usarid @damipoo any thoughts on this, today and in future versions of RAML?


#3

Hi @comptly,
Thanks for the suggestion - this is what I am falling back on at the moment.
I would really like the ability to fully describe the files as these are fully part of my API (and BTW, this is valid for downloads as well!).

My use case: I am working on the bulkification of an API, where the uploaded file contains the definition of each query to execute in a job. Similarly, the download-able files contains the results of the job.
The file formats are an integral part of the API definition!


#4

I don’t have any more thoughts right now, except that it’s indeed a good candidate to consider for a future RAML version. Interesting to realize, as you have @egiraudy, that the file itself could have multiple specs depending on its media type.


#5

@usarid any hint on when, roughly, there would be a next version of the spec and the scope of the changes?


#6

I would guess later this summer. With the increasing traction and growing developer community, there is now a good accumulation of suggestions as well as a healthy and now experienced community to provide feedback on candidates to the spec.


#7

Got you, thanks!


#8

OK, look for a list of candidates coming in the next few days, with finalization into a new RAML 1.0 spec soon thereafter.


#9

I am reviewing github issues targeted for 1.0 and I guess https://github.com/raml-org/raml-spec/issues/94 is the candidate you are referring to, correct?
Unless i miss something, It seems this would not allow properly documenting the format(s) for the uploaded file :frowning:

Also, it seems there is nothing to address documenting the format a download-able files, correct?