[Route("/Widget/{Id}", "PUT", Summary = "Updates a widget by Id.")]
public class UpdateWidgetReq : IReturn<string>
{
[ApiMember(IsRequired = true)]
public Guid Id { get; set; }
[ApiMember(IsRequired = true, ParameterType = "body", DataType = "WidgetDTO")]
public WidgetDTO widgetUpdate { get; set; }
}
How do I make Swagger generate and display the WidgetDTO model for the widgetUpdate property? Leaving the DataType off has Swagger expecting a string, which doesn’t help the end-user understand the json structure they need to submit at all (which is the whole purpose of even having swagger here). Specifying the name of the WidgetDTO type as I have above, or even fully qualified, causes the Swagger to show “undefined” as the type (and still no model shown).
according to the ServiceStack code for the DataType field:
For path, query, and header paramTypes, this field must be a primitive. For body, this can be a complex or container datatype.
Not that it should matter, but I set DisableAutoDtoInBodyParam to true since that auto generated DTO was confusing, given the Id Path param.
NuGetting version 4.5.9 seems to have resolved this as the model now shows for the complex type without any DataType param specified.
On a related question - is there any way to enable the default body param DTO on a call by call basis if the default is disabled? Alternatively, I don’t mind leaving it enabled, if there was a way for it to auto exclude params marked as “path.” It’s confusing to consumers that we are asking for the Id param in the path of the call and then the docs are asking for it again in the body.
DataType property can only be one of the Open API predefined types, it can not be user-defined type. List of all types which can handle DataType you can find in Open API specification (see type column). Swagger UI and Autorest do not support complex datatypes (with only some exception like lists) and that’s why the string type is used to describe input parameters which have user-defined type.
You can annotate DTO member with [ApiMember(ExcludeInSchema=true)] attrubute as mentioned in OpenApi plugin docs and this member will not be shown in body parameters (but will be shown as path param).
Thanks. You may want to update your comment in code then on the DataType field here. As I quoted it above, it says it can be complex types for a body param.