Swagger / OpenAPI Annotation for tags

ServiceStack Open API
1

Thanks for adding OpenAPI to the mix!

I was testing the new feature and noticed that the Tags auto generated are using the Route or Path of the endpoint.
Would it be possible to add a Tags annotation to allow multiple endpoints to be grouped together using the swagger
specs.

tags [Tag Object] A list of tags used by the specification with additional metadata. The order of the tags can be used to reflect on their order by the parsing tools. Not all tags that are used by the Operation Object must be declared. The tags that are not declared may be organized randomly or based on the tools’ logic. Each tag name in the list MUST be unique.

For example:
/Movies/
/Movies/{Id}
/Movies/{Id}/Videos

Could share the tag “Movies” and also “Entertainment” so that they are grouped together rather than all having their own individual tag, which is how it appears now.

thanks!
Bob

2

You can use OperationFilter to add (or remove) tags to operation

Plugins.Add(new OpenApiFeature
{
    OperationFilter = (verb, operation) => operation.Tags.Add("all operations")
});

Also you can use ApiDeclarationFilter to finally edit generated specification and make a changes to tags or any other section.

Here is the documentation about filters you can use with OpenApiFeature plugin.

3

Thanks for the quick response. I am a little unclear how I would modify a tag based on certain operations.
Can I do some kind of case when operation.OperationId = “xyz”, operation.Tags.Add(“abc”);

thanks,
Bob

4

Disregard. I have it now.

OperationFilter = (verb, operation) => operation.Tags.AddRange(GetOperationTag(operation.OperationId))

thanks for your help.

Bob

5

You can do something like this:

Plugins.Add(new OpenApiFeature
{
    OperationFilter = (verb, operation) => 
    {
        if (operation.OperationId.StartsWith("MoviesDto_"))
        {
            operation.Tags.Add("Entertainment");
        }
    }
});

OperationId is unique and is created as concatenation of DTO type name and operation postfix (_Get, _Post, _Delete, _Create for PUT verb and _Update for PATCH), thats why you should check start of the string. If you want to know all generated Operation Ids, you can open http://yoursite/openapi URL, get json from it and watch on "operationId" properties.

6

And of course you can implement it that way as you wrote.

7

For those wanting the behaviour similar to that of Swagger 1.2, where it groups the routes in the SwaggerUI on the first part of the route - then this worked for me:

AppHost.Plugins.Add(new ServiceStack.Api.OpenApi.OpenApiFeature() 
{ 
    OperationFilter = (verb, operation) => 
    { 
        var path = operation.Tags[0]; 
        operation.Tags.Clear();
        operation.Tags.Add(path.Split('/').SkipWhile(string.IsNullOrEmpty).First()); 
    } 
});
1 Like