C# ServiceStack Attribute and Swagger UI - List of complex objects

Question

What would be the proper way of using annotation in C# for Swagger-UI in order to have a definition of complex objects listed.

For example, if we have something like this:

  [ApiMember(Name = "Foo", Description = "Some description", 
DataType = "List<Foo>", IsRequired = true)]    
public List<Foo> Foo {get; set;}

So, if I use it like that, swagger-ui will just show in documentation that this is a List but not link or anything to Foo.

I mean, it's shown properly in model \ schema, but just not listed in the field definition, is that how it's suppose to work, or it can be changed to point to exact data structure which is expected in the list \ array?

EDIT Here's the full DTO sample:

[Route("/warranties", "POST", Summary = "POST New Warrantty", Notes = "Create new warranty into our system")]
public class CreateWarrantyRequest : IReturn<ApiResponse>
{
    [ApiMember(Name = "CoverageId", Description = "Coverage Id", DataType = "int", IsRequired = true)]
    public string CoverageId { get; set; }

    [ApiMember(Name = "WarrantyProducts", Description = "Warranty Products", DataType = "List<WarrantyProduct>", IsRequired = true)]
    public List<WarrantyProduct> WarrantyProducts { get; set; }
}

public class WarrantyProduct
{
    [ApiMember(Name = "Manufacturer", Description = "Manufacturer Name", DataType = "string", IsRequired = true)]
    public string Manufacturer { get; set; }
    [ApiMember(Name = "ProductType ", Description = "Product Type", DataType = "ProductType", IsRequired = true)]
    public ProductType ProductType { get; set; }
    [ApiMember(Name = "SerialNumber", Description = "Serial Number", DataType = "string", IsRequired = true)]
    public string SerialNumber { get; set; }
    [ApiMember(Name = "PurchasePrice", Description = "Purchase Price", DataType = "decimal", IsRequired = true)]
    public decimal PurchasePrice { get; set; }    
}

And this is how it looks with SwaggerFeature:

And this is how it looks with OpenApiFeature:

mythz · Accepted Answer · 2017-11-02 18:39:39Z

2

The DataType is for specifying a known type. Defining complex Types like List<T> is done by specifying an array Type with its items referencing the Complex Type schema, e.g:

{
  "description": "A complex object array response",
  "schema": {
    "type": "array",
    "items": {
      "$ref": "#/definitions/VeryComplexType"
    }
  }
}

This is what ServiceStack does automatically without specifying the DataType, Complex Types can't be defined using [ApiMember].

answered Nov 2, 2017 at 18:39

mythz

144k31 gold badges253 silver badges400 bronze badges

Sign up to request clarification or add additional context in comments.

7 Comments

ShP Over a year ago

how come that when using SwaggerFeature I got model schema for request but when using OpenApiFeature it's not shown, and also when using OpenApiFeature it shows "undefined" for data type. Can you show some C# example for this, maybe I'm doing something wrong?

mythz Over a year ago

@ShP They're 2 different specifications that are consumed using 2 different versions of Swagger UI. Like I've said there is no way to define complex types using attributes, but ServiceStack already emits the appropriate complex type definition according to the Open API spec.

ShP Over a year ago

I am little bit confused, you said SS already emits the appropriate complex type, but in OpenApi for my object says "undefined" and it is not listed in model schema as well...

mythz Over a year ago

@ShP It should emit the appropriate type info by default, like my answer. If you’re seeing undefined with default behaviour (I.e without [ApiMember]) please update your question with a screenshot showing the issue and full DTO class definitions you’re using.

ShP Over a year ago

O.o oh ok, my bad, it's working fine now! Thanks for your help once again. :)

|

Collectives™ on Stack Overflow

C# ServiceStack Attribute and Swagger UI - List of complex objects

1 Answer 1

7 Comments

Your Answer

Linked

Hot Network Questions

Collectives™ on Stack Overflow

1 Answer 1

7 Comments

Your Answer

Sign up or log in

Post as a guest

Linked

Related