In my journey from front-end developer to full-stack developer, coming to grips with API creation and functionality is a major part of the learning curve. Enter the Open API Specification and swagger.yaml.
For those who don't know, Swagger, is not only a tool enabled by annotations to allow for browsing, testing and documentation of existing APIs. It also enables the design and specifications of APIs. Typically, writing working code is expensive and takes times. Discovering errors during and after creation are costly to the development process and good design can reduce and avoid these errors.
As such, an API can be designed and documented via a .yaml (or .json) file. This file can then be displayed and interacted with via the Swagger UI to better design and visualise the API being created. Importantly, this .yaml file can be committed to a repo and shared with the team, which means it can be collaborated upon.
Having spent the majority of the past few years working with completely undocumented APIs and more recently, having spent the better part of the last year working on a web application which consumes a third party API (poorly designed - in my opinion). I believe, I have become acutely aware of the following shortcomings in API design:
While the benefits of Swagger in terms of the first three points above have been clear to me for some time. By creating a .yaml file in conjunction with the SwaggerUI the real power of Swagger and the OpenAPI spec comes to the fore. You are now able to avoid the final point by thinking through the API, step by step, using the guidance and best practice of the Open API via the low cost and low impact of the .yaml file. One is then able to share and easily modify an API before a single line of code is written. As such, in the case of a team project, the architect or lead developer could design the API and then share it with the team in order to get feedback from the others. Being able to see the entire API as well as interact with it to some extent, allows the development team to better understand the scope and possible shortcoming of the desired implementation.
Being able to view and share these specifications means you can quickly and easily learn from other specs while designing and collaborating on your own spec. This spec can then, once ready to get started, be run through a mock generator to allow the front-end team to start working without having to wait for the backend developers to complete the API. Now that the API spec is known, both front and back-end developers have a contract against which to develop and more importantly, know what to expect!
Changes in API spec are now more easily known and discoverable since the spec is committed to repo and can be included into the PR process.