I have the following API, defined using ServiceStack, for which the documentation is not generating correctly.
public class User
{
public string Name { get; set; }
public int Id { get; set; }
}
[Route("/users", "PUT")]
public class UpdateUsersRequest : IReturn<List<User>>
{
[ApiMember(DataType = "array", Description = "Users to be updated", ParameterType = "body", IsRequired = true)]
public List<User> UsersToUpdate { get; set; }
}
public class UsersService : Service
{
public List<User> Put(UpdateUsersRequest request)
{
return new List<User>();
}
}
If I specify the ApiMember attribute (as shown above), I get the following documentation, where the description is shown correctly, but the example value is incorrect.
Also, ServiceStack is never able to parse the body (see examples below) and I always get a SerializationException with a message:
Type definitions should start with a '{', expecting serialized type 'UpdateUsersRequest', got string starting with: ["{","
\"UpdateUsersRequest\": {"," \"Us"*.
Example 1: only the array.
[ { "Name": "string", "Id": 0 } ]
Example 2: the property.
{ "UsersToUpdate": [ { "Name": "string", "Id": 0 } ] }
Example 3: complete object.
{
"UpdateUsersRequest": {
"UsersToUpdate": [
{
"Name": "string",
"Id": 0
}
]
}
}
I also tried not adding the ApiMember attribute, as mentioned here. This generates the example correctly, and I can use it to send values to my request. However, there is no description shown, and I get an extra row for the UsersToUpdate property.
If I specify any value here, it again results in a SerializationException.
My question: How can I generate the documentation correctly, such that the description and examples are shown correctly, and I do not end up with an extra useless row?
Note: I also tried creating a wrapper object around the list, but that doesn't work either and again results in a SerializationException. This will likely not be an acceptable solution as it will end up changing the existing customer scripts to execute the APIs, but mentioning it here anyway.
