Include extact HTTP content in case of Multipart

[LasneF]

When using multipart it can be confusing especially when dealing with array

in the case describes

  content:
    multipart/form-data:
      schema:
        type: object
        properties:
          id:
            # default for primitives without a special format is text/plain
            type: string
          addresses:
            # default for arrays is based on the type in the `items`
            # subschema, which is an object, so `application/json`
            type: array
            items:
              type: object
              properties : 
                 street: 
                    type: string
                 city 
                    type : sting

it can be interesting to add the exact HTTP content

Rationnal : Prism fails to do validation of such structure ,
several AI tool chatbot replies divergent / not correct answer from the truth (or may be i am wrong still they are confused)
looks they are mixing the content , with the parameter name

Content-Type: multipart/form-data; boundary=--------------------------002292520254007945318895

----------------------------002292520254007945318895
Content-Disposition: form-data; name="id"
Content-Type: application/json
"32d49c7f-566c-4d07-9f13-08e74fb5c464"
----------------------------002292520254007945318895
Content-Disposition: form-data; name="addresses"
Content-Type: application/json
{
"street" : "4726 Earth Street"
"city" : "Houston"
}
----------------------------002292520254007945318895
Content-Disposition: form-data; name="addresses"
Content-Type: application/json
{
"street" : "4 Moon Street"
"city" : "Edwards"
}

----------------------------002292520254007945318895--

and not something with

----------------------------002292520254007945318895
Content-Disposition: form-data;
Content-Type: application/json
{
"addresses" : [ { "street" : "4 Moon Street" , "city" : "Edwards"} ,
{ "street" : "4726 Earth Street" , "city" : "Houston" } ]
}

[handrews]

@LasneF I strongly agree. In fact I thought I included such an example, but I remember that the syntax highlighting was a mess and I put it on the back burner and never got around to it. I know @ralfhandl fixed syntax highlighting for query string examples — This is more complex, but perhaps we could figure it out? I remember finding a highlighter somewhere that would correctly read the Content-Type per-part field and use the appropriate syntax highlighter (e.g. JSON, XML, plain text) on each part.

[ralfhandl]

@handrews Please create a PR adding such an example and let's see how it gets rendered and what can be improved.

[LasneF]

i will give it a try with a with the above content , @ralfhandl is there a way to check the renderer page of a branch ?

[handrews]

@LasneF npm run build-src (I have filed #4433 to document this)

[lornajane]

@LasneF Don't worry about the rendering, if you can fix the content then we can help with the rest (but as @handrews already commented, the instructions are already better on how to see it locally)

[handrews]

@LasneF I did add some really basic multipart syntax highlighting support which is now available. Which would not support full HTTP syntax highlighting but could get closer and might be a good starting point for more rendering support.

I also just added a lot more multipart examples in #4589, so this would be even more useful. And we have precedent in that we should XML output for the XML Object examples, and URI output for urlencoded examples.

[LasneF]

i have just seen the additions and all the job on the various content type

i wondering if we should not add the sample mentionned on top , to clearly express than in multi part each field is a dedicated part
and in case of an array , it is handled by duplication of the part, one for each element of the array

but i am not sure as it could be set that it is "just" HTTP even if to me related to OAS implementation leveraging HTTP

[LasneF]

👍 got that soem part are already been merged for instance in this PR
https://github.com/OAI/OpenAPI-Specification/pull/4562/files
the precision is added so far it is better let's close this one , if ever need update will create another one , but the concern is addressed