Monday, February 26, 2018

Adding Swagger to an ASP.NET Core 2.0 app

Swagger is an API specification framework. It reminds me of WSDL in the SOAP days. In this article I will guide you in add Swagger documentation to an ASP.NET Core Web API app.

There are three components that we need to buckle-up in our Web API application. These are, not surprisingly, called Swashbuckle:
  1. Swashbuckle.AspNetCore.SwaggerGen : builds SwaggerDocument objects from your router, controllers and models.
  2. Swashbuckle.SwaggerUI : embedded version of Swagger UI tool which uses the above documents for a rich customizable experience for describing the Web API functionality and includes built in test harness capabilities for the public methods.
  3. Swashbuckle.AspNetCore.Swagger: Swagger object model and middleware to expose SwaggerDocument objects as JSON endpoints.
For starters, add package Swashbuckle to your project. This can be done in two ways:

1) If you are using Visual Studio 2017, execute the following command from the Package Manager Console:

install-package --version 2.1.0 Swashbuckle.AspNetCore

You can find the Package Manager Console in Visual Studio 2017 at Tools >>  NuGet Package Manager >> Package Manager Console.

2) From a terminal window in the main project folder, enter the following command:

dotnet add package Swashbuckle.AspNetCore -Version 2.1.0

Add the following using statement at the top of your Startup.cs file:

using Swashbuckle.AspNetCore.Swagger;

Next, add the Swagger generator to bottom of the ConfigureServices() method in Startup.cs:

// Register the Swagger generator, defining one or more Swagger 
// documents
services.AddSwaggerGen(c => {
  c.SwaggerDoc("v1", new Info { Title = "My API", Version = "v1" });
});

Add the following two lines of code to the Cofigure() method in Startup.cs just before app.UseMvc():

// Enable middleware to serve generated Swagger as JSON endpoint
app.UseSwagger();

// Enable middleware to serve swagger-ui (HTML, JS, CSS, etc.)
// specifying the Swagger JSON endpoint.
app.UseSwaggerUI(c =>
{
  c.SwaggerEndpoint("/swagger/v1/swagger.json", "My API V1");
});

NOTE: You can exclude the service generated by an API controller by annotating the controller class with: [ApiExplorerSettings(IgnoreApi = true)]

Run your application with CTRL + F5.

Point your browser to http://localhost:{port number}/swagger/v1/swagger.json and you will see a JSON document that describes the endpoints of your service.

image

You can also see the Swagger UI at URL http://localhost{port number}/swagger.

image

In the above example the API service is Studentapi. Your service will be under API V1. Click on it and you will see something similar to the following:

image

To test out GET, click on the first blue GET button and the section will expand describing to you the structure of your object:

image

Click on the “Try it out!” button to view the data coming back from the service for all items in the collection:

image

Click on the first blue GET button again to collapse the section. Now, click on the second blue GET button to test retrieval of an item by id.

image

Enter a value for ‘id’ then click the “Try it out!” button. It should get for you the item for that id.

image

In a similar manner, go ahead and test out all the other POSTDELETE, and PUT buttons.

The official Swagger website at http://swagger.io/. You can generate a Swagger client for most programming languages at http://editor.swagger.io/.

No comments:

Post a Comment