Swagger / OpenAPI Annotation for tags

bobk · March 30, 2017, 8:30pm

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

xplicit · March 30, 2017, 1:59pm

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.

bobk · March 30, 2017, 5:01pm

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

bobk · March 30, 2017, 5:25pm

Disregard. I have it now.

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

thanks for your help.

Bob

xplicit · March 30, 2017, 5:30pm

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.

xplicit · March 30, 2017, 5:33pm

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

mikesheen · March 31, 2017, 2:23am

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()); 
    } 
});