Setting up Swagger to help formed API endpoints in ASP.NET Core

Forming of your endpoints is critical particularly on the off chance that you host third party customers of your REST API benefit. Any adjustment in your endpoint, for instance in information structure may affect customers regardless of whether it is in reverse perfect, customers may process your endpoint information in various ways, so notwithstanding adding one extra property to your model may likewise affect usefulness of the customer which is expending your endpoint.


There are diverse methodologies in forming your endpoints and you can check some of them in Advanced forming in ASP.NET Core Web API article. My most loved is the course based forming, for the straightforward reason which is that expending rendition can be effectively decided from the URL customer is utilizing to execute HTTP technique against. Different techniques are similarly helpful and powerful, it;s simply my genuine belief.

In this article I am will utilize Swagger to report and depict formed endpoint of the ASP.NET Core WebAPI benefit and the administration will utilize course based forming. So gives begin with our demo a chance to extend and first include Nuget bundle references.

Before we begin coding and adding Swagger to the reliance infusion and the pipeline of WebAPI application, we have to include some venture settings thet will guarantee Swagger can get our created XML documentetion from the manufacture result and some fundamental undertaking meta information.

NOTE: in .NET Core AssemblyInfo.cs isn’t a piece of the undertaking layout any longer, so on the off chance that you need t utilize it, you have to include it physically. Othrewise, you can add your get together metadata to the undertaking document straightforwardly and perused them basically a similar way you would peruse them from AssemblyInfo.cs class

We will utilize this information to assemble portrayal in our Swagger occurrence and show them to the client.

Venture structure

Presently how about we perceive how are we going to arrange out API adaptations. Since forming and changes may reflect controllers, as well as our models or DTOs also, we will contain every one of them in a different envelope for each variant.

The task structure should look something like this


We are bouncing our entire demand setting to the rendition, so you can adjust the two controllers and models free in their very own form namespace keeping you current adaptation flawless from the progressions you may do on your new API variant.

For the demo in this article I will utilize straightforward POCO class as a model and the change for the new form will comprise in including extra field in the model.

The adaptation of the controller must be likewise set by the ApiVersion trait with the goal that course gets took care of legitimately.

Swagger wire up

Presently when we have our task structure set up and we have the system to arrange our variants, we can begin incorporating Swagger to our venture. We as of now have the references added to the task, so the main stem is to add Swagger to our reliance infusion in the Startup.cs

First thing that is dealt with in the startup reliance infusion arrangement is course. For this we are utilizing API Explorer Option to portray the manner in which we need our course to be produced by the verion of the endpoint. More data about the adaptation designing you can discover in Version Format page on ASP.NET forming storehouse page

Remeber we added some meta to our ptoject? Well presently it’s an ideal opportunity to utilize them. We will peruse our task meatadata and show it as a documentation on our Swagger occurrence endpoint.

You likely seen that we are referencing SwaggerDefaultValues class in our code. This is a custom usage of IOperationFilter interface and it is utilized to set archive the API form by Swagger.

When we have all setup in the reliance infusion administrations, we have to add Swagger to the pipeline, with the goal that our solicitations to Swagger course get dealt with legitimately. We do this by including Swagger and SwaggerUI in the Configure technique in Startup.cs class

Presently everything is prepared for the single adaptation test, however before we hit F5, let arrange our startup in launchSettings.json document to target Swagger course on the startup of the application

We are prepared to test the single rendition Swagger endpoint

You can see that Swagger figured out how to get the model XML portrayal added to the class and all the AssemblyInfo data got from thr venture document. Presently we should include a minor refresh the model to test our new form of the API endpoint.

As we have segregated rendition organizer V1 for our variant 1.0, we’ll include new envelope for adaptation 2.0 with name V2 where we will store our new form controller and model. The change we will execute in another variant is Description field added to the model

Controller for V2 is essentially the equivalent with contrast of referencing the new model namespace V2 rather than V1

Also, now when we run the API venture we’ll see two choice in the spec list in upper right corner with our new form V2. When we swith to it, we’ll have our new endpoint depiction with our new portrayal recorded in the model