How to pursuade the ApiExplorer to create documentation for ExpandoObject?

Question

I've created a very neat way of implementing a PATCH method for my Web.API project by making use of an ExpandoObject as a parameter. As illustrated below:

[HttpPatch, Route("api/employee/{id:int}")]
public IHttpActionResult Update(int id, [FromBody] ExpandoObject employee)
    {
        var source = Repository.FindEmployeeById(id);
        Patch(employee, source);
        Repository.SaveEmployee(source);
        return Ok(source);
    }

However, when generating documentation ApiExplorer is at a loss as to what to do with the ExpandoObject, which is totally understandable. Would anyone have any ideas on how to manipulate the ApiExplorer to provide some sensible documentation?

My idea was to maybe introduce an new attribute which points to the actual Type that is expected:

public IHttpActionResult Update(int id, [FromBody, Mimics(typeof(Employee))] ExpandoObject employee) 
{ 
    ... 
}

But I have no idea where to start, any ideas or suggestions are welcome.

Answer 1

So this has been the source of some late evenings in order to get the Api Explorer to play along with our developed Http Patch mechanism. Truth be told, I'd probably should do a bit of a proper write up to full explain the mechanics behind the whole idea. But for those of you who landed on this page because you want the Api explorer to use a different type in the documentation, this is where you need to look:

Open HelpPageConfigurationExtensions.cs and locate the following method:

//File: Areas/HelpPage/HelpPageConfigurationExtensions.cs
private static void GenerateRequestModelDescription(HelpPageApiModel apiModel, ModelDescriptionGenerator modelGenerator, HelpPageSampleGenerator sampleGenerator)
{
    ....
}

this is the location where the parameter information is available to you and also provides you with the ability to replace/substitute parameter information with something else. I ended up doing the following to handle my ExpandoObject parameter issue:

if (apiParameter.Source == ApiParameterSource.FromBody)
{
    Type parameterType = apiParameter.ParameterDescriptor.ParameterType;

    // do something different when dealing with parameters 
    // of type ExpandObject.
    if (parameterType == typeof(ExpandoObject))
    {
         // if a request-type-attribute is defined, assume the parameter
         // is the supposed to mimic the type defined.
         var requestTypeAttribute = apiParameter.ParameterDescriptor.GetCustomAttributes<RequestTypeAttribute>().FirstOrDefault();
         if (requestTypeAttribute != null)
         {
             parameterType = requestTypeAttribute.RequestType;
         }
    }
}

Just, note that the RequestTypeAttribute is something I devised. My WebApi endpoint looks like this now:

public IHttpActionResult Update(int id, 
    [FromBody, RequestType(typeof(Employee))] ExpandoObject employee)

Thank you to everyone who took time to look into the problem.