How to use ServiceStack OpenApiFeature/Swagger with api description and response examples? - servicestack

Question

Is there a way to add a description to the api (not just to individual routes) and update api version and add example responses/resquests using the OpenApiFeature in ServiceStack? I can't find anything in the documentation about these pieces of the swagger ui.
I tried using the Api attribute to add the description but that doesn't seem to work.

Answer 1

The only declarative Attributes that can annotate individual Services are documented on the Open API docs. Here's a fully annotated example:
[Tag("TheTag")]
[Api("SwaggerTest Service Description")]
[ApiResponse(HttpStatusCode.BadRequest, "Your request was not understood")]
[ApiResponse(HttpStatusCode.InternalServerError, "Oops, something broke")]
[Route("/swagger", "GET", Summary = #"GET / Summary", Notes = "GET / Notes")]
[Route("/swagger/{Name}", "GET", Summary = #"GET Summary", Notes = "GET /Name Notes")]
[Route("/swagger/{Name}", "POST", Summary = #"POST Summary", Notes = "POST /Name Notes")]
public class SwaggerExample
{
[ApiMember(Description = "Color Description",
ParameterType = "path", DataType = "string", IsRequired = true)]
[ApiAllowableValues("Name", typeof(MyColor))] //Enum
public string Name { get; set; }
[ApiMember]
[ApiAllowableValues("Color", typeof(MyColor))] //Enum
public MyColor Color { get; set; }
[ApiMember(Description = "Aliased Description", DataType="string", IsRequired=true)]
[DataMember(Name = "Aliased")]
public string Original { get; set; }
[ApiMember(Description = "Not Aliased", DataType="string", IsRequired=true)]
public string NotAliased { get; set; }
[ApiMember(IsRequired = false, AllowMultiple = true)]
public DateTime[] MyDateBetween { get; set; }
[ApiMember(Description = "Nested model 1", DataType = "SwaggerNestedModel")]
public SwaggerNestedModel NestedModel1 { get; set; }
[ApiMember(Description = "Nested model 2", DataType = "SwaggerNestedModel2")]
public SwaggerNestedModel2 NestedModel2 { get; set; }
}
The other annotation Open API allows is grouping logical operations by Tag which you would use annotate in ServiceStack with the [Tag] attribute that you can then provide a description for when registering the OpenApiFeature Plugin, e.g:
Plugins.Add(new OpenApiFeature
{
Tags =
{
new OpenApiTag
{
Name = "TheTag",
Description = "TheTag Description",
ExternalDocs = new OpenApiExternalDocumentation
{
Description = "Link to External Docs Desc",
Url = "http://example.org/docs/path",
}
}
}
});