Multipart request body example

[VasylSulakov]

Hi, maybe I just don't get it right, but how do I provide Examples for a Post action that accepts both application/json and multipart/form-data? As well, it seems that I have to provide an extra "fake" required body parameter comment just to provide an extra mime supported (multipart/form-data in my case)

No feedback/error from parsing components is a nightmare, HOURS getting spent for trying out absolutely legal strings to go for an example.

So, imagine a multipart/form-data request with some extra parameters with it:

public static string multipartExample =
@"---------------------------acebdf13572468
ParamaterOne: 'Some App-Specific Data'
ParameterTwo: { ItemOne: 'one', ItemTwo: 'two' }
ParameterThree: ['1','2','3']
Content-Disposition: 'form-data'; name='fieldNameHere'; filename='AnnualReport.docx'
Content-Type: 'application/vnd.openxmlformats-officedocument.wordprocessingml.document'
<@includeC:\Users\Anderssen\Desktop\AnnualReport.docx@>
---------------------------acebdf13572468";

So, the string above is absolutely valid and can be used to fulfill the request, yet it would not go through the CSharpAnnotations.

Any help will be highly appreciated!
Thanks

[Shwetap05]

@VasylSulakov There is just so much that we can design around VS comments so i hear your pain. And will try to justify the design choices that are made around these tags. You will need to document each content-type separately as corresponding examples for those types are nested inside the same tag which is more cleaner approach then creating a single tag with multiple content-type then specify those content-type again in example tags to get the mapping b/w two.

That said can you please provide the /// comments from your code and i will take a look to figure the issue out.

[VasylSulakov]

Hi, @Shwetap05, thanks for the fast reply! Basically, my main problem as of now is to bring in that multipart string from my first post into an example section like that

<param name="MultipartContent" cref="string" type="multipart/form-data" required="true" in="body">
<example>
<value><see cref="MyController.multipartExample"/></value>
</example>
</param>

[Shwetap05]

@VasylSulakov for big example strings like that you should use them in tag which looks correct to me. So now coming to the issue of example value not being populated in the generated document. Can you please check if the GenerationDiagnostic result from the generator contains any errors?

[VasylSulakov]

Well, that's the hardest part of examples - there are no errors in the GenerationDiagnostic, so I have to guess what's wrong with my string, which could drive you absolutely mad after you spend hours on it.

[Shwetap05]

@VasylSulakov this is definitely a bug, the generator should throw an error if its not able to parse the example value or if there are other issue. i will investigate this and get back on it.

[Shwetap05]

@VasylSulakov Investigated and i am able to repro this and there are two issues:

1. OpenAPI.NET.CSharpAnnotations issue: where its ignoring the diagnostics result from OpenAPI.NET when parsing the example value instead of throwing a generation error for it, I will be working on a fix for this.

exampleValue = new OpenApiStringReader().ReadFragment(
field.GetValue(null).ToString(),
OpenApiSpecVersion.OpenApi3_0,
out OpenApiDiagnostic openApiDiagnostic);

2. OpenAPI.NET issue: OpenApiStringReader().ReadFragment is throwing error while trying to parse the example value you have provided. i will log an issue for it on https://github.com/Microsoft/OpenAPI.NET

[VasylSulakov]

@Shwetap05 thank you!

[Shwetap05]

OpenAPI.Net issue microsoft/OpenAPI.NET#345