如何将 ServiceStack OpenApiFeature/Swagger 与 api 描述和响应示例一起使用？

Question

有没有办法向 api 添加描述（不仅仅是单个路由）并更新 api 版本并使用 ServiceStack 中的 OpenApiFeature 添加示例响应/请求？我在文档中找不到关于这些 swagger ui 的任何内容。

我尝试使用 Api 属性添加描述，但这似乎不起作用。

Answer 1

唯一的 declarative Attributes that can annotate individual Services 记录在 Open API 文档中。这是一个完整注释的示例：

[Tag("TheTag")]
[Api("SwaggerTest Service Description")]
[ApiResponse(HttpStatusCode.BadRequest, "Your request was not understood")]
[ApiResponse(HttpStatusCode.InternalServerError, "Oops, something broke")]
[Route("/swagger", "GET", Summary = @"GET / Summary", Notes = "GET / Notes")]
[Route("/swagger/{Name}", "GET", Summary = @"GET Summary", Notes = "GET /Name Notes")]
[Route("/swagger/{Name}", "POST", Summary = @"POST Summary", Notes = "POST /Name Notes")]
public class SwaggerExample
{
    [ApiMember(Description = "Color Description",
               ParameterType = "path", DataType = "string", IsRequired = true)]
    [ApiAllowableValues("Name", typeof(MyColor))] //Enum
    public string Name { get; set; }

    [ApiMember]
    [ApiAllowableValues("Color", typeof(MyColor))] //Enum
    public MyColor Color { get; set; }

    [ApiMember(Description = "Aliased Description", DataType="string", IsRequired=true)]
    [DataMember(Name = "Aliased")]
    public string Original { get; set; }

    [ApiMember(Description = "Not Aliased", DataType="string", IsRequired=true)]
    public string NotAliased { get; set; }

    [ApiMember(IsRequired = false, AllowMultiple = true)]
    public DateTime[] MyDateBetween { get; set; }

    [ApiMember(Description = "Nested model 1", DataType = "SwaggerNestedModel")]
    public SwaggerNestedModel NestedModel1 { get; set; }

    [ApiMember(Description = "Nested model 2", DataType = "SwaggerNestedModel2")]
    public SwaggerNestedModel2 NestedModel2 { get; set; }
}

Open API 允许的另一个注解是 grouping logical operations by Tag，您可以在 ServiceStack 中使用带有 [Tag] 属性的注解，然后您可以在注册 OpenApiFeature 插件时提供描述，例如：

Plugins.Add(new OpenApiFeature
{
    Tags =
    {
        new OpenApiTag
        {
            Name = "TheTag",
            Description = "TheTag Description",
            ExternalDocs = new OpenApiExternalDocumentation
            {
                Description = "Link to External Docs Desc",
                Url = "http://example.org/docs/path",
            }
        }
    }
});