Service Fabric: Create Stateless Web Api with Asp.Net.Core and Generate Api Doc with Swagger.io

ไทย/Eng
Service Fabric is a scalable and reliable microservices. Service Fabric mainly consists of 2 main services: Stateless (does not maintain a mutated state) and Stateful (maintain a mutated state) microservice. This article implemented the web API that did not store any state of data so stateless service had been chosen (Stateful also the same for this purpose).

Swagger.io is a powerful framework that helps developers to design, document RESTful Web Services. There are many libraries for using Swagger.io in Asp.Net Core framework. One of my favorite is Swashbuckle because of ease of use and it also provides the auto-generation of API document according to your controllers.

Prerequisite

  1. Visual Studio – This article used VS2017 Preview 2 with .NET Version 4.6.1
  2. Service Fabric SDK – See How

Full source code of this project is availabled on GitHub

Let’s Start

    1. Open Visual Studio and Create New Project

    1. In the service page, choose Stateless ASP.NET Core

    1. First, you have to install 2 NuGet packages: “Swashbuckle.AspNetCore” and “Microsoft.AspNetCore.StaticFiles”

    1. Open a file named “Startup.cs”
    2. In “Configure” method, add these lines of code.
app.UseSwagger();
app.UseSwaggerUI(c =>
{
    c.SwaggerEndpoint("/swagger/v1/swagger.json", "My API V1");
});
    1. Deploy to cluster (this article used localhost). Then, go to your cluster explorer (For local cluster, the url is “https://localhost:19080/Explorer/”). Finally, go to your app to get the url endpoint.

    1. Go to “http://localhost:8994/swagger/”, you will see the api document generated by Swagger.io

    1. Swashbuckle will generate all of the APIs from all controllers in your project. If you want to hide some methods or classes, you can achieve this by adding the following attribute to the methods or classes you want to skip from the document.
[ApiExplorerSettings(IgnoreApi = true)]
    1. Assuming I want to skip ValuesController from this document so I put the attribute from previous step to ValuesController. The result will look like this.

 

Now, everytime you implement the web APIs it will automatically generate the document for you. Easy right? But you can’t insert the description of the APIs to your document yet. If you want to, you have to setup the .NET build-in XMLDocument.

    1. Go to project’s property. In the “Build” tab, check the “XML documentation file”. The xml file path will appear, copy the filename for now. In the following figure, the filename is “PersonApi.xml”

    1. Open “Startup.cs” again and modify the ConfigureServices and it should look something like this.
public void ConfigureServices(IServiceCollection services)
{
    services.AddMvc();
    services.AddSwaggerGen(c =>
    {
        c.SwaggerDoc("v1", new Info { Title = "My API", Version = "v1" });

        var basePath = AppContext.BaseDirectory;
        var xmlPath = Path.Combine(basePath, "PersonApi.xml");
        c.IncludeXmlComments(xmlPath);
    });
}
    1. XMLDocument can be inserted by using “///”followed by the XML that specifies you APIs right above the methods. The example of using XMLDocument of “Get” method of ValuesController can be shown as following.
// GET api/values
/// 

/// Retrieves all values
///

/// Awesomeness! /// There are the values /// No values found /// Cannot retrieve values for a moment. [HttpGet] [ProducesResponseType(typeof(List), 200)] [ProducesResponseType(typeof(IDictionary), 400)] [ProducesResponseType(typeof(void), 500)] public IEnumerable Get() { return new string[] { “value1”, “value2” }; }

    1. The result will be look like this.

  1. For the further features of the .NET XMLDocument and Swagger document. I will discuss about it in the next post.

See you on next post.
Happy Coding.

Leave a Reply

Your email address will not be published. Required fields are marked *