Hello, I have a question about the automatic documentation page.
I have prepared DTO for the request (and the response) using class inheritance, because most of the attributes are common, as in the following example:
[Route("/content/{culture}photos/{id}", "GET", Summary = "GET a photo by id")]
public class PhotoRequest : BaseRequest, IReturn<PhotoResponse>
{
}
which derives from:
[DataContract]
public class BaseRequest: CoreRequest
{
[DataMember(Name = "id")]
[ApiMember(Description = "The ID", ParameterType = "path", IsRequired = true)]
public string Id{ get; set; }
}
and more:
[DataContract]
public class CoreRequest
{
[DataMember(Name = "Culture")]
[ApiMember(Name = "Culture", ParameterType = "path", IsRequired = true, Description = "The culture (e.g.: en-GB)")]
public string Culture { get; set; }
}
In the metatada page (xml / json detail page for example) there are two big issues:
the PhotoRequest class is missing from the page
The BaseRequest and CoreRequest classes are present, but without any relations between them, so it is not easy to understand from the consumer of the request
The things do not change marking abstract the two base classes.
The same classes are properly documented on the Swagger page.
Any ideas to solve this issue? Do I have to remove the inheritance and duplicate all the attributes?
You’re making things confusing by treating your Request DTOs as an implementation detail that you’re trying to DRY and hide behind multiple classes instead of treating it as its intended purpose as the source of reference for your Services Contract. This makes it harder for anyone who wants to look at your Request DTO to find out what your Services accepts, who have to build a mental model in their head of multiple layers of inheritance with a schema definitions that they can’t see as they’re looking at each of your Request DTOs.
If you’re going to use inheritance I wouldn’t go more than 1-level deep. Trying to split out a base class over multiple base classes makes your API contract unnecessarily confusing whilst yielding very little benefit. Limiting it to 1-level would make things less confusing since the name of your base class would indicate it’s a base Request DTO class. If you only had 1 base class I would call it RequestBase which clearly conveys its purpose. If you multiple Request Base classes I would use a name that describes what the base class is about, e.g. if all Photo Services inherited the same base class you could call it PhotoRequestBase. Calling something CoreRequest just looks like you’re introducing an artificial name with no clear purpose.
The code in my question was a sample to demonstrate the limitations;.I undestand that ServiceStack auto doc feature does not support inheritance, so I will deal with it.