An introduction to OpenAPI specification, Swagger Editor, and Swagger UI
Have you heard of APIs that are developed and documented by Swagger?
Yes, Swagger is hot these days. This novel approach uses the OpenAPI Specification, formerly called the Swagger Specification. After many years of API freedom, there is finally an industry standard to design, build, test, document, and use RESTful APIs.
Here is the definition from https://swagger.io/.
“Simplify API development for users, teams, and enterprises with the Swagger open source and professional toolset. Find out how Swagger can help you design and document your APIs at scale.”
Swagger is all about the APIs. UI developers are the consumers of APIs, and thus it is a big plus to know about the OpenAPI Specification and Swagger tools. For open source, there are Swagger Editor, Swagger UI, Swagger Codegen, and Swagger Plugins. For enterprise version, there are SwaggerHub and Swagger Inspector.
By understanding how Swagger works, UI developers become more capable to perform UI work or even full-stack work. In this article, we focus on the OpenAPI Specification, Swagger Editor, and Swagger UI.
OpenAPI Specification
The OpenAPI Specification (OAS) is a specification for machine-readable interface files for describing, producing, consuming, and visualizing RESTful web services. It describes API endpoints, input and output parameters, authentication methods, etc. OAS is a community-driven open specification within the OpenAPI Initiative, a Linux Foundation Collaborative Project.
API definitions can be written in YAML or JSON. In a previous article, we explained that YAML is a recursive acronym for “YAML Ain’t Markup Language.” It is a human-readable data serialization language. In fact, YAML is a superset of JSON which provides additional features on namespace, comment, attribute support, and more.
The following is the YAML definition of a pet store, an official example from the OpenAPI Specification 3.0.
YAML is extremely human readable and self-explanatory.
Line 1 specifies the openapi version to be 3.0.0. This field is required.
Lines 2–6 specify info, which is required to provide metadata about the APIs. Among them, title and version are required.
#javascript #programming #web-development #ui
