In this article we will learn about Swagger UI.
1. Introduction
The OpenAPI specification defines the standard of describing HTTP API for any project. This is programming-language agnostic. This helps humans and computers to know about the System/API without the need to look into the code. If the specification is properly implemented it helps a consumer to understand the interaction with the remote system effectively without much hassle.
OpenAPI specification can be compared to an Interface in Java. Interfaces in Java define the contract between the client and the server. It tells the caller what it needs to send and the expected value which will be returned. This helps the caller to reduce the guesswork. Similarly, OpenAPI is a specification that defines how to document your HTTP API so that the consumer of your API has to do minimal guesswork.
One of the big use cases for a machine-readable API definition is to automatically generate the Client code. The OpenAPI documents are generally described in YAML or JSON. The best part is that these documents can be created statically or generated at runtime. One this to note is that OpenAPI can not be integrated with all the available HTPP API implementations – but they are available for RESTful HTTP Apis. The current version of OpenAPI specification is 3.1.0.
2. Swagger UI
With Swagger UI the producers, as well as the consumer of the API, can interact with the resources without knowing the implementation details of those APIs. It’s automatically generated from your OpenAPI (formerly known as Swagger) Specification, with the visual documentation making it easy for back-end implementation and client-side consumption. It helps you quickly find and work with resources and endpoints with neatly categorized documentation.
You can check a sample UI here. You can also use SwaggerHub to host your Swagger UI.
3. Summary
In this article first, we looked at what is an OpenAPI specification and what it is used for, then we looked at the Swagger UI implementation of this specification.
