ASP.NET Core 2.2 & 3 REST API #22 — Extended Swagger Documentation

Theodoros Ntakouris
4 min readAug 5, 2019

Up Next: Creating an API SDK with Refit

Let’s review what swagger actually is and start using some more of the features it has to offer.

Swagger basically is a way to describe our API. It contains many fancy features like the Swagger UI we have been using throughout this series to view how our endpoints look like as in path, request, response and auth contracts. This tool comes in handy especially when collaborating with other developers:

  • Mobile or Frontend developers can use this to work on the frontend of the app without looking at backend source code
  • Business people can use this to test things fast
  • QA can use this to rapidly test or reproduce bugs
  • Other Backend engineers that consume our API can take a look at this as documentation

Currently, we only take advantage of the automatic conversion of our endpoints, with some type inference in order to provide some dummy generated test data.

Moving on

We’re going to implement a new SwaggerInstaller and move all the swagger stuff from our MvcInstaller over there.

Swagger is able to provide more stuff on the UI and the spec, by using a generated XML file. You don’t need to remember the following code by heart, it’s just boilerplate. We’re basically auto-generating an XML file and adding it into the dependency injection container.

Add the following Property Group to your .csproj in order to allow documentation generation:

We are now ready to extend what swagger can do.

Examples

We can now use method summary comments in order to get documentation generated and presented on the UI:

This is simple enough, but we can take this a step further. We can even specify multiple response codes and sample requests to try out:

This type of comment is not at all maintainable and can be outdated really fast (remember, the only source of truth is the actual code itself). We’re going to leave the response code and the summary parts as-is, but let’s take this a step further into a more code-defined documentation.

  • Add the Swashbuckle.AspNetCore.Filters package
  • Register the examples from the current assembly via services.AddSwaggerExamplesFromAssemblyOf<Startup>(); in our swagger installer, as well as add the filter by x.ExampleFilters() on our AddSwaggerGen method.
  • Create a directory called SwaggerExamples as well as Requests and Responses subdirectories
  • Once again we will stick with the naming convention XRequest , XResponse ← → XRequestExample , XResponseExample convention.

We can start creating classes like CreateTagRequestExample : IExamplesProvider<CreateTagRequest> , implementing the only method this interface is made of as follows.

This is going to auto detect all the examples that are present and show then in the swagger UI and the XML file, properly serialized to JSON.

The same thing can of course be done with the responses.

Some extra work needs to be done because we have never specified our return types, we just return IActionResult . We can easily do this via the [ProducesResponseType(typeof(T), statusCode)] . That’s enough to let us know what we return on which status code. We can now see a more complete example.

There’s a small error in the final screenshot. Can you spot it? The content type header is wrong. Everything should be application/json instead. We can specify this at the controller level, with the [Produces("application/json")] attribute.

Up Next: Creating an API SDK with Refit

Code is available on Github and the instructional videos are located on YouTube.

Keep Coding

--

--