In this article we will learn about OpenAPI specification and how swagger implements it.
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. OpenAPI implementation through Swagger
There are lots of implementations of the OpenAPI specification but the most commonly used is Swagger. You can find other implementations here. Swagger UI helps the consumer to understand the API logic behind the implementations. The UI is dependency-free and is supported by all browsers. You can also use SwaggerHub to host your documents. According to the website :
SwaggerHub visually renders your API contract as a fully interactive document for live workability, letting your end consumers know exactly how your API will work and behave, before integrating it into their code
We can also use Swagger Inspector to generate OAS documentation for our existing APIs. It also allows you to import your existing OAS-based API definitions from web or a local file-system. You can protect you hosted documentation in SwaggerHub with the in-build security feature.
We can use Swagger Editor to design and document out OpenAPI-based APIs. Swagger Codegen can simplify your build process by generating server stubs and client SDKs for any API, defined with the OpenAPI specification, so your team can focus better on your API’s implementation and adoption
3. Conclusion
In this article, we looked at what OpenApi specification is and what it is used for. Then we discussed one of the most common implementations of the OpenApi specification – Swagger. We discussed how Swagger makes the documentation of the REST API simple and dynamic. In the end, we discussed some of the most commonly used Swagger tools.
