ServiceStack OpenAPI路由/标记描述

Question

我已将项目升级为使用最新版本的ServiceStack并使用OpenApiFeature而不是SwaggerFeature。

我在RouteSummary中指定的描述用于在Swagger中显示，但在OpenApi下，它们似乎不受尊重。是否有新的地方或我在配置中遗漏了什么？

Plugins.Add(new OpenApiFeature
{
    RouteSummary = {
        { "/clubs", "Customer club lookups" },
        { "/customers", "Customer demographics, receipts and transactions" },
        { "/dates", "Fiscal date breakdowns" }
    }
});

Answer 1

SwaggerFeature遵循Swagger 1.2规范，该规范将API列表与API Resource Object允许您为路径集合指定描述的规范分离。但是，Open API v2.0规范中的组合Open API规范删除了此功能。

这已被Open API Tags取代，我在this commit中添加了显式支持，您可以使用相同的标记对要显示的操作进行分组，例如：

[Tag("clubs")]
[Route("/clubs", "GET")]
public class GetClubs {}

[Tag("clubs")]
[Route("/clubs/{Id}", "PUT")]
public class UpdateClub 
{
    public int Id { get; set; }
}

然后，您可以在注册OpenApiFeature时为每个标记指定说明，例如：

Plugins.Add(new OpenApiFeature
{
    Tags =
    {
        new OpenApiTag
        {
            Name = "clubs",
            Description = "Customer club lookups",
        },
        new OpenApiTag
        {
            Name = "customers",
            Description = "Customer demographics, receipts and transactions",
        },
        new OpenApiTag
        {
            Name = "dates",
            Description = "Fiscal date breakdowns",
        },
    }
});

新的Tags集合可从 v4.5.13 获得，现在为available on MyGet。