Better way to do API documentation using Swagger

I would like to discuss my perspective and opinion on using swashbuckle versus swagger UI to develop the API documentation. Till a few weeks back swashbuckle was my go-to for creating or generating webapi documentation. Now I prefer the alternative approach. I scoured the internet in search of an alternative approach and all of the solutions was to use swashbuckle.

Swashbuckle is a wonderful package to generate documentation. The main and probably the most important disadvantage of using swashbuckle to create the documentation is, the developer needs to add a ton of annotation and code to generate the documentation. If the documentation needs update or correction, the correction has to be made to the comments in the code and recompiled and published again.

The alternative approach is to use swagger UI and write the API specification separately. I detail below how to implement the alternative approach.

Implementing Swagger UI

My alternative approach is to use swagger UI files and the Open API specification

Create a Web API2 application

Download the Swagger-UI from the github project. The project has a folder call dist and the dist folder has the swagger UI ready for distribution.

Create the API specification using the swagger editor and export the specification into a JSON file.

Create a folder in the application to place the swagger UI static files, in my project I call it swaggerUI.

SwaggerUI Folder In Project

Create a folder to place the API specification files, I named the OASDoc in my project.

Specify the API specification file URL in the relative path in the index.html file in swagger ui folder

 const ui = SwaggerUIBundle({
            urls: [
                    url: "/OASDoc/v1openapi.json",
                    name:"Version 1.0.0"
        dom_id: '#swagger-ui'

Last but not the least, I created a MVC controller and in HomeController->Index Action, I’m redirecting to the swagger index.html file to automatically redirect the url to the index.html.

Please find the sample project in the link below .

Advantages of using  Swagger UI

The advantage I see in using Swagger UI and not swashbuckle is the fact that in case of any changes in documentation the code and the documentation are separate and there is no need to recompile or touch the code to update the documentation. All I have to do is update the API specification file and replace that file and my documentation is updated.

Problems Encountered

After creating and testing the documentation and the UI in my box, I migrated the changes to the remote server, but the remote server and the Swagger UI was throwing an error “Failed to load API definition”

The issue was because of the remote IIS server could not serve the JSON (API specification) file format. I found this after I tried to access the specification file directly from the browser using the URL. The fix for this is to either add the MIME type to the server or use the MIME type mapping in the Web.Config file. The MIME type mapping for the configuration file is given below.

    <mimeMap fileExtension=".json" mimeType="application/json"/> 

My question in StackOverflow and GitHub issue is given in the references.

Sample Code



Site Footer