Document response classes with Swagger and ServiceStack

Question

In the petstore example from wordnik they have provided documentation for their response classes. An example can be seen on the /pet/{petId} endpoint:

Pet {
    name (string, optional),
    id (integer, optional): foo,
    category (Category, optional),
    photoUrls (array[string], optional),
    tags (array[Tag], optional),
    status (string, optional) = ['available' or 'pending' or 'sold']: pet status in the store
}

It looks like it supports the following parameters:

• optional (flag that specifies if the property will always be in the response)
• allowed values
• description

Is there a way to accomplish this with the ServiceStack implementation?

Answer 1

Here's what the ServiceStack Swagger implementation currently supports, as of version 3.9.59:

• Optional: only nullable value types are described as optional. Other than that, there is currently no support for explicitly defining which properties in the request/response body are optional. For path or query string parameters, you can control optionality using ApiMemberAttribute
• Allowed values: enum types will automatically get a list of allowed values. For other types (e.g. a string property with a predefined set of values), annotate the property with the ApiAllowableValues attribute
• Description: use the System.ComponentModel.Description attribute

Make sure your request DTO implements the IReturn<ResponseDtoType> interface.

The following is probably the closest approximation to the Petstore example I can think of, given the current ServiceStack Swagger implementation:

public class Pet
{
    public string Name { get; set; }
    [Description("foo")]
    public int? Id { get; set; }
    public Category Category { get; set; }
    public List<string> PhotoUrls { get; set; }
    public List<Tag> Tags { get; set; }

    // If "Status" is implemented internally as a string
    [Description("pet status in the store")]
    [ApiAllowableValues("Status", "available", "pending", "sold")]
    public string Status1 { get; set; }

    // If you can implement "Status" as an enum, the allowable values
    // are instead automatically documented:
    [Description("pet status in the store")]
    public Statuses Status2 { get; set; }

    public enum Statuses { available, pending, sold }
}

The only property in that DTO that will get marked as optional is Id.