Fast and interactive API documentation with Swagger



Creating an API documentation when working with any kind API framework is almost mandatory.
Of course except if you are not the only one who is using the API endpoints, it that case don't read this... Otherwise you should.

Doing the documentation manually can be a annoying and continues work. By continues I mean that it's not enough to create the documentation once And leave it like this forever..

This is why this is not a good approach if you value your time and efforts. The developers are always looking for the easiest and smarter way of doing things.
Here I will present you how can you do your full API documentation, with the minimum effort of installing NuGet package and adding a few lines of code.

*If you hate to read badly written text in English and want to get to the action and see how is implemented in a project. Check this link with implementation of swagger

The NuGet package is called Swashbuckle and the version that the example is using is 4.0.0 and it's done with MVC 5.

When install this package in your web project you will be automatically provided with a configuration file called SwaggerConfig placed in App_Start folder.
You will have to update this file to like this:


 public class SwaggerConfig
    {
        public static void Register()
        {

            Swashbuckle.Bootstrapper.Init(GlobalConfiguration.Configuration);

            // NOTE: If you want to customize the generated swagger or UI, use SwaggerSpecConfig and/or SwaggerUiConfig here ...

            SwaggerSpecConfig.Customize(c =>
            {
                var path = GetXmlCommentsPath();
                if (!File.Exists(path))
                {
                    XmlDocument doc = new XmlDocument();
                    XmlNode Root = doc.AppendChild(doc.CreateElement("doc"));
                    doc.Save(path);
                }
                
                c.IncludeXmlComments(path);
            });

        }
		
        protected static string GetXmlCommentsPath()
        {

            return System.String.Format(@"{0}\bin\CarsApp.Web.XML", System.AppDomain.CurrentDomain.BaseDirectory);
        }
    }
	
Example of SwaggerConfig file

This method Register() is called automatically when the project is started. So you don't have to do anything else.
Doing that is absolutely enough and you can start using your documentation. You will be able to find it at:
  • locally - localhost:{port}/swagger
  • live - {your domain}/swagger
The result that you will get is pretty good interface containing expandable tabs for each different API controller.
  • Within each tab (controller) are it's methods. (or API endpoints).
  • Moreover there is a description on each endpoint parameters.
  • Also there is a 'Try It Out' button which makes a call to the endpoint, which is great for debugging.

swagger-screenshot


*Again if you want to use it directly in a prepared template. You can get it here

Check out our 3 minute Swagger Video!