Combining multiple Swagger API endpoints in a single UI

Multiple REST API microservices endpoints in a single Swagger UI

Shifting from traditional monolithic application architecture to micorservices can solve bunch of problems and issues monolith application application design approach introduces, but on the other hand it has it's own drawbacks, although number of drawbacks compared to number of problems it solves is a lot greater so it makes sense to take a path in process of moving from monolithic to micorservices.

On of the steps to move to micorservices is to physically have your services running as individual processes. This also means that in case of REST API type of applications you will have multiple instances and each of these instances will have it's own endpoints and documentation for them. This can significantly help to client developers or third parties which will consume your service. Often this may significantly affect success of the final software product.

Swagger is amazing way to document your API by simply decorating method in your ASP.NET Core application. Once up and running Swagger UI will take car of rendering UI for your API endpoints and you get your API documentation out of the box. In addition libraries and tools such as NSwag or Autorest.

Multiple microservices Swagger UI

Swagger UI works great for cases you have a single REST API service. However, once you start breaking your robust monolith REST service, things get complicated. A soon as you break your existing service into two or more services, you end up with two service URL which often are served from the same IP (orchestrator, load balancer or just simply host machine) on a different port. This creates a mess with documentation and therefore it makes your service harder to consume as documentation is not in the proper order and clients have to keep track of the different urls for the different micorservice REST APIs.

Unfortunately this functionality does not come out of the box, but there is a solution. To keep things simple, I did not create a separate ASP.NET Core application that would maybe connect to Consul or some other service discovery to dynamically populate UI with service endpoints. The following solution is rather a static website with list of endpoints of your microservices.

So let's start

• as first step download or clone Swagger UI repository
• create a folder where you will have your static webiste which will list services
• inside repository folder on your machine, locate following files (swagger-ui.css, swagger-ui-bundle.js, swagger-ui-standalone-preset.js) and copy them to your static website application folder
• create index.html file in the static webiste folder and update it with the content from file of the same name which you can download from here along with all css and js files mentioned above

Attached sample is pointing to sample Pet Store and Weather APIs but you can easily update it by just changing the script section of index.html

window.onload = function() {
  
  // Build a system
  const ui = SwaggerUIBundle({
    urls: [ 
		{ url: "http://petstore.swagger.io/v2/swagger.json", name: "Pets" },
		{ url: "https://idratherbewriting.com/learnapidoc/docs/rest_api_specifications/openapi_openweathermap.yml", name: "Weather" }
    ],
    "urls.primaryName": "Pets",
    dom_id: '#swagger-ui',
    deepLinking: true,
    presets: [
      SwaggerUIBundle.presets.apis,
      SwaggerUIStandalonePreset
    ],
    plugins: [
      SwaggerUIBundle.plugins.DownloadUrl
    ],
    layout: "StandaloneLayout"
  })

  window.ui = ui
}
    

You can see that services are registered in the UI with simple object that contains OpenAPI JSON definition and API name added to the array. By simply altering this array, you can simply add and remove your services from the UI.

Once you spin up this static website you will have Swagger UI with list of these two services.

By switching from one service to another from a list, you will get the Swagger UI rendered out based on the Open API definition.

Customizing Swagger UI

Now it is always nice to add that final touch and brand your service documentation to comply with your application or service visual design. Customizing this simple service hub is pretty similar to customizing Swagger in ASP.NET Core application.

All you need it to add and reference custom CSS file which will override Swagger UI styles. Here is a sample one you can fin in the .zip file attached to this article.

.swagger-ui .topbar .download-url-wrapper input[type=text] {
    border: 2px solid #77889a;
}

.swagger-ui .topbar .download-url-wrapper .download-url-button {
    background: #77889a;
}

.swagger-ui img {
    display: none;
}

.swagger-ui .topbar {
    background-color: #EDEDED;
	border-bottom: 2px solid #C1C1C1;
}

.swagger-ui .topbar .download-url-wrapper .select-label {
	color: #3B4151;
}

.swagger-ui .topbar .topbar-wrapper {
    background-repeat: no-repeat;
	padding:10px;
	background-size: contain;
    background-image: url("/api-logo.svg");
}

    

Configurable ASP.NET Core MVC web application

Static website is fine if you need to do something fast and have your services Swagger UI grouped in one place. However, on a long run you may want to introduce configuration with discovery services and static files wont be an easy way to achieve this.

For this purpose I created a simple ASP.NET Core Web Razor View application which in this example reads available services from the configuration JSON file. Source code of this simple application is available from public GitHub repository https://github.com/dejanstojanovic/swagger-ui-hub/tree/master/Swagger.UI.Hub.

Since it is pretty straight forward, there is not need to add much logic in a separate views. Main layout razor view is doing all the rendering because technically you do not have any elements except the ones that come with already preloaded Swagger UI.

References

• Swagger UI - GitHub
• Autorest
• NSwag
• Swashbuckle.AspNetCore.SwaggerUi
• Swashbuckle.AspNetCore.Swagger
• Swashbuckle.AspNetCore.SwaggerGen
• freeicons.io
• https://editor.method.ac/
• Sample - Pet Store API Swagger definition
• Sample - Weather API Swagger definition

Disclaimer

Purpose of the code contained in snippets or available for download in this article is solely for learning and demo purposes. Author will not be held responsible for any failure or damages caused due to any other usage.

About the author

DEJAN STOJANOVIC

Dejan is a passionate Software Architect/Developer. He is highly experienced in .NET programming platform including ASP.NET MVC and WebApi. He likes working on new technologies and exciting challenging projects

CONNECT WITH DEJAN