ServiceStack 在 Open API (Swagger UI) 问题中记录正文参数

Question

我正在寻找使用 Open API 插件在 ServiceStack API 中记录正文参数的任何方法。它在为查询或路径参数编写时显示正确的文档，但是有什么方法可以为正文中的参数执行此操作吗？

Answer 1

如果您分配了所有属性，那么它应该在 Swagger 中可见 UI，您只需单击位于每个示例值上方的“模型”选项卡。

以上是使用以下类型创建的：

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; }
}

由于 ServiceStack 只是生成 OpenApi 2.0，您可以使用任何支持它的 Swagger UI（或 reader）。使用较新的 Swagger UI，您的 body 架构的表示会更紧凑。

ServiceStack 在 Open API (Swagger UI) 问题中记录正文参数

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

servicestack

openapi