ServiceStack documenting body parameters in Open API (Swagger UI) Issue

Question

I am looking for any way to document body parameters in ServiceStack API with Open API plugin. It is showing proper documentation when written for query or path parameters but is there any way to do it for parameters in body?

Answer 1

If you have all of the attributes assigned then it should be visible in the Swagger UI, you just have to click the "model" tab that sits above each example value.

The above was created using the types below:

public enum TestType
{
    ValueA,
    ValueB,
    ValueC,
    ValueD
}

[DataContract]
public class TestA
{
    [
        DataMember(Order = 1),
        ApiMember(
            Name = "PropertyA", 
            Description = "A test property showing an integer type", 
            ParameterType = "model", 
            DataType = "integer", 
            Format = "int32", 
            IsRequired = true
        )
    ]
    public int PropertyA { get; set; }

    [
        DataMember(Order = 2),
        ApiMember(
            Name = "PropertyB", 
            Description = "A second test property showing a string type",
            ParameterType = "model",
            DataType = "string",
            IsRequired = true
        )
    ]
    public string PropertyB { get; set; }

    [
        DataMember(Order = 3),
        ApiMember(
            Name = "PropertyC",
            Description = "A third test property showing a string enum type.",
            ParameterType = "model",
            DataType = "string",
            IsRequired = true
        ),
        ApiAllowableValues("PropertyC", typeof(TestType))
    ]
    public string PropertyC { get; set; }

    [
        DataMember(Order = 4),
        ApiMember(
            Name = "PropertyD",
            Description = "A fourth test property showing a nested type.",
            ParameterType = "model",
            IsRequired = true
        )
    ]
    public TestB PropertyD { get; set; }

}

[DataContract]
public class TestB
{
    [
        DataMember(Order = 1),
        ApiMember(
            Name = "PropertyA",
            Description = "A test property showing an integer type",
            ParameterType = "model",
            DataType = "integer",
            Format = "int32",
            IsRequired = true
        )
    ]
    public int PropertyA { get; set; }

    [
        DataMember(Order = 2),
        ApiMember(
            Name = "PropertyB",
            Description = "A second test property showing a string type",
            ParameterType = "model",
            DataType = "string",
            IsRequired = true
        )
    ]
    public string PropertyB { get; set; }

    [
        DataMember(Order = 3),
        ApiMember(
            Name = "PropertyC",
            Description = "A third test property showing a string enum type.",
            ParameterType = "model",
            DataType = "string",
            IsRequired = true
        ),
        ApiAllowableValues("PropertyC", typeof(TestType))
    ]
    public string PropertyC { get; set; }

}

[
    Route(
        "/test",
        "POST",
        Summary = "POST to test documentation in Swagger UI."
    ),
    Api("Test"),
    Tag("Swagger UI Documentation"),
    ApiResponse(
        HttpStatusCode.BadRequest,
        "Your request was not understood or failed validation.",
        ResponseType = typeof(PostTestResponse)
    ),
    ApiResponse(
        HttpStatusCode.InternalServerError,
        "Oops, something broke.",
        ResponseType = typeof(PostTestResponse)
    ),
    DataContract
]
public class PostTest : IReturn<PostTestResponse>
{
    [
        DataMember(Order = 1),
        ApiMember(
            Name = "QueryStringA", 
            Description = "A query string parameter",
            ParameterType = "query",
            DataType = "string",
            IsRequired = false,
            ExcludeInSchema = true
        )
    ]
    public string QueryStringA { get; set; }

    [
        DataMember(Order = 2),
        ApiMember(
            Name = "Test",
            Description = "Posted test data",
            ParameterType = "model",
            IsRequired = true
        )
    ]
    public TestA Test { get; set; }
}

[DataContract]
public class PostTestResponse : IHasResponseStatus
{
    [
        DataMember(Order = 1),
        ApiMember(
            Name = "ResponseStatus",
            Description = "Information about any issue that may have occurred",
            ParameterType = "model",
            IsRequired = false
        )
    ]
    public ResponseStatus ResponseStatus { get; set; }

    [
        DataMember(Order = 2),
        ApiMember(
            Name = "Test",
            Description = "Returned test",
            ParameterType = "model",
            IsRequired = false
        )
    ]
    public TestA Test { get; set; }
}

Since ServiceStack just generates OpenApi 2.0, you can use any Swagger UI (or reader that supports it). Using the newer Swagger UI you get a less cramped representation of your body schema.