CODEWITHSUNDEEP
servicestackswagger-uiopenapi
Robert Petty
Robert Petty

Reputation: 397

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

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.

Upvotes: 1

Views: 294

Answers (1)

mythz
mythz

Reputation: 143319

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

Upvotes: 2

Related Questions