Taking WAPI Documentation to the Next Level using Swagger

Introduction

Swagger is an open-source software framework backed by a large ecosystem of tools that helps developers design, build, document, and consume RESTful web services. While most users identify Swagger by the Swagger UI tool, the Swagger toolset includes support for automated documentation, code generation, and test-case generation. Sponsored by SmartBear Software, Swagger has been a strong supporter of open-source software and has widespread adoption.

Reasons to use Swagger

1. It is comprehensible for developers and non-developers
2. It is human-readable and machine-readable
3. It is easy to use
4. One does not need to have coding knowledge to use it

Infoblox WAPIs

The Infoblox WAPI is an interface based on REST (REpresentational State Transfer). It uses HTTP methods and supports the primary or most-commonly-used HTTP verbs: POST, GET, PUT, and DELETE. These correspond to create, read, update, and delete (or CRUD) operations, respectively. It supports input and output in JSON and XML. All API calls are encrypted using SSL/TLS and authenticated using HTTP basic authentication.  These do not depend on any programming language.  

What’s new in WAPIs with NIOS 8.6?

NIOS 8.6 comes with a new WAPI version v2.12 and has added support for v2.11.1 released with NIOS 8.5.1. Objects added in the new WAPI versions are: 

1. WAPI v2.12:  “discovery:credentialgroup”
2. WAPI v2.11 and v2.11.1: “discovery:sdnnetwork”, “parentalcontrol:subscriberrecord”, “pxgrid:endpoint”, “threatanalytics:analytics_whitelist”

Infoblox WAPI documentation using Swagger

This solution uses Swagger to give the Infoblox WAPIs a visual representation. Swagger supports the Open-API-Specification (OAS) and uses the definition to create a user-interface for visualization of the APIs making it easy for the user to understand and work with defined APIs. The solution accepts the WAPI version as a parameter and documents all the API-endpoints for the selected WAPI version.

Swagger definition for Infoblox WAPIs makes it really easy to work with the APIs. 

All WAPI objects till version v2.12 are documented. The Swagger user-interface for Infoblox WAPIs  looks like this:

Why do you need to use this solution?

1. No need to know any curl commands or programming language-specific constructs to try out WAPIs
2. No need to download any tool like Postman or Insomnia
3. It serves as a playground to understand the structure and working of the APIs
4. It provides a “try it out” feature that enables users to familiarize with the APIs

What’s new with Swagger v3?

1. Added support for WAPI version v2.12 released along with NIOS 8.6.
2. Added support for v2.11.1 (minor WAPI version released with NIOS 8.5.1). 
3. Updated GUI with SSL verification during documentation generation.
4. Automated the definition generation for all supported WAPI versions.

Demo Video

You can watch this video for a quick demo of Infoblox DDI (NIOS) integration with Swagger.

 

Resources

• Swagger Docker Image for Infoblox WAPIs is available here
• Swagger Documentation is available on GitHub 
• NIOS RESTful API reference documentation.

Conclusion

Swagger makes it really easy for the user to understand the structure and working of the Infoblox APIs without going through the entire documentation and allows the user to play around with the APIs without having any working knowledge about WAPIs or implementation details.