- Swashbuckle Pro Tips for ASP.NET Web API – Content Types
- Swashbuckle Pro Tips for ASP.NET Web API – Example/s Using AutoFixture
In the previous post, we implemented
IOperationFilter of Swashbuckle to emit the
produces properties in a Swagger document. This post will implement another
IOperationFilter to emit
example(s) properties containing auto-generated values by AutoFixture.
The sample codes used in this post can be found here.
The sample application uses the following spec:
example(s) in Operation Object
There are a few places, in a Swagger definition, where example objects are declared:
Swashbuckle library automatically generates those example data with default values based on their data type. In other words, if its data type is string, the example value becomes
string, if its data type is number, the example value becomes
0, and so on:
Is there any way that we can have a sort of meaningful data in those example objects? Of course there is. This NuGet package helps us create more meaningful example objects. Download the package and write some codes like:
Then add a decorator to an action of Web API:
The first one,
SwaggerResponse, is built-in Swashbuckle decorator and the second one,
SwaggerResponseExample is what we’re going to use for example data generation. Once the decorator is added, we need to add another
OptionFilter acton in the Swagger config file like:
Reload the Swagger UI page and we can see the example object with more meaningful values:
This is how the Swagger definition looks like:
This is certainly a good way to show example data. But when we refresh the page, the example objects still show the same value as we hard-coded them.
Automatic Example Data Generation with AutoFixture
We were able to generate an example object by implementing
Swashbuckle.Examples library. What if we want to create an example object with automatically generated values?
AutoFixture is for unit testing by generating a fixture instance with random values. Why not using this for our randomly generating examples? Let’s have a look. This time, we create an abstract class to apply both requests and responses.
The abstract class,
ModelExample, internally implements
AutoFixture and creates a random instance of the type
T. Here are request and response classes inheriting the abstract class:
And this is the action method of a Web API.
SwaggerRequestModel defines the request example and
SwaggerResponseExample defines the response example.
Reload the Swagger UI page several times.
Each time the page is refreshed, the example objects have different values. If we need to put some restrictions like string length or value range, we can simply put other decorators like
Range on those request/response models.
So far, we have walked through how Swashbuckle library could generate example(s) object with meaningful values rather than default values. There are many other cases that we can customise Swashbuckle library to enrich Swagger document. I’ll introduce some other cases later on.