ServiceStack OpenAPI Route/Tag 描述

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 allowed you to specify a description for a collection of routes. However the combined Open API Specification in the Open API v2.0 规范删除了此功能。

这已被替换为 Open API Tags, which I've added explicit support for in 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.

ServiceStack OpenAPI Route/Tag 描述

ServiceStack OpenAPI Route/Tag Description

c#

servicestack

swagger-ui

servicestack-openapi