c# - 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 中的联合开放 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 .