How to design and document your APIs with the SwaggerHub suite?

How to design and document your APIs with the SwaggerHub suite?

Author : Thomas Plantain (API & Integration Manager at Astrakhan) - Published date : July 23, 2021


In the first article about API design tools, we presented the Stoplight suite. For this second article, we will introduce the SwaggerHub suite from the website from Smartbear.

Smartbear has been offering an open-source tool for testing web services for several years, called SoapUI.

SoapUI is essential for automating web services tests. It supports SOAP and REST formats and HTTP/HTTPS and JMS protocols.

One of SoapUI’s assets is the validation of WSDLs, the interfaces of web services.

With the massive arrival of REST APIs in the digitalization strategy of companies, Smartbear has developed the ReadyAPI tool which is a complete version of SoapUI for testing web services and APIs.


The SwaggerHub suite focuses on API design, i.e. defining the interface of services that will be exposed to partners or internal applications of the information system.

Swagger offers both an open-source and a pro version.

The main tool of the solution is Swagger UI which allows to graphically visualize the JSON file (or YAML) which defines the interface of an API, we talk about the OpenAPI standard (formerly Swagger, hence the name of the suite).

If the graphical representation of the interface is very well done, we can see in the following example that the JSON code is sometimes hard to read.

The editor allows you to have both the JSON code and the graphical rendering on the same page, while the tool displays the errors present in the JSON code.

The Pro version of SwaggerHub allows you to create a team and work on the same OpenAPI or Swagger files:

Swagger files can be automatically synchronized with GitHub.

SwaggerHub allows you to work in a team to define API interfaces, in a pure Design-First spirit. Clients can be created in the most popular languages, and stubs can be generated for services.

Combined with ReadyAPI for API testing, a complete solution is available for teams developing and deploying REST APIs. The documentation of the APIs will be easier to write, and the user experience will be improved.