ServiceStack OpenAPI Route/Tag Description

Question

I've upgraded my project to use the latest version of ServiceStack and to use the OpenApiFeature instead of the SwaggerFeature.

The descriptions I specified in the RouteSummary used to display in Swagger, but under OpenApi they don't seem to be respected. Is there a new place for these or am I missing something in my config?

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

score 3 · Accepted Answer · answered Jun 27 '17 at 03:15

The SwaggerFeature follows the Swagger 1.2 Specification which decoupled the list of APIs from their specification where the 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 specification removed this feature.

This has been replaced with Open API Tags, which I've added explicit support for in this commit where you can group operations you want displayed together using the same tag, e.g:

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

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

You can then specify a description for each tag when registering the OpenApiFeature, e.g:

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",
        },
    }
});

The new Tags collection is available from v4.5.13 that's now available on MyGet.

Thanks for adding support for this so quickly. You're awesome! — Connor, Jun 27 '17 at 12:28

ServiceStack OpenAPI Route/Tag Description

1 Answers1