We talk with developer Michael Melody about his experience working on the updated open source plugin and the SwaggerHub platform
Teams who are already OpenAPI users recognize the value of the centralized SwaggerHub solution but migrating and configuring a large number of service definitions can feel like a tedious process. Over the past few weeks, the SwaggerHub team made significant updates to the open source build plugin to easily automate this workflow and allow teams to more quickly on-board to the platform.
The first feature brings the ability to batch migrate definitions onto SwaggerHub. Directories of OpenAPI definitions can be parsed and pushed into the platform, greatly reducing the amount of time it takes to get started and organize a new centralized environment.
To more easily tie definitions back to code the plugin now automatically configures an SCM integration to create a bi-directional relationship between the definition stored in SwaggerHub, and the one being generated and deployed as part of a build environment. As changes are made to a definition they are automatically pushed to a repository configured during the build. This functionality allows teams to leverage the power of OpenAPI whether they have traditionally been design or code first in their development practice.
To learn more about the plugin and the work around it we spoke with one of SwaggerHub’s Galway based developers, Michael Melody, about his experience working on the plugin, balancing open source and paid development tasks, and his views on the design first approach to API development.
How long have you been a part of the SwaggerHub team?
I joined in the summer of 2018. Being a developer here in Galway and having used SmartBear products in previous employments, I’ve always been aware of SmartBear’s presence in the city. When the role came up, I jumped at the chance to join the team!
What is your development background? Have you worked on other open source projects in the past?
Having left in college in 2014, I’ve been developing professionally for almost 5 years. Working on open source has always been an ambition of mine but one I had never followed through on. It’s been a good experience getting involved in open source so far.
The updates to the plugin are really going to empower a lot of organizations looking to migrate on to the platform – what was the development effort for the changes? Was it a solo project, or was there a group of developers working on this?
There was a huge push from the entire team to get the plugin to where it is today. The plugin was originally born from a hackathon held here in Smartbear. One of our previous developers (shout out to John French - even though he’s left us, he’s continued to contribute via PR’s) devised the plugin to enable us to fetch API definitions as part of the build process.
More recently, as part of the latest releases there were a number of us working to get this over the line and ensure it was of the highest quality; from developers who participated in design discussions and reviewed pull requests to QA who put the plugin through its paces when testing.
Was there a rough timeline the team followed?
In terms of a timeline, we planned to develop both the plugin and make the changes to the SwaggerHub backend over 3 of our 2-week sprints. We were able to achieve this by breaking down what was required to deliver v1.0.3 into 3 smaller chunks of development:
- Multi-definition upload
- Required SwaggerHub backend updates
- GitHub integration provisioning
In retrospect, we could have released the plugin after the first sprint to deliver some of that functionality earlier than we did. That’s something we’ll take on board for future development.
The plugin is part of a larger collection of open source projects that SmartBear supports, from the Swagger tooling to SoapUI for API testing - are you typically involved in the SwaggerHub platform, or supporting the open source projects?
Yes, for the most part I’m involved solely on the SwaggerHub platform. As part of my role here on the development team, I work with the open source developers when releasing the latest Codegen changes into SwaggerHub. For me, that involves testing certain features and making the necessary changes on the SwaggerHub side to incorporate them.
Do you think SmartBear’s approach to supporting both a paid solution like SwaggerHub, as well as the open source tooling is an advantage?
I mentioned Codegen earlier, which itself is open source and a part of the SwaggerHub product. For me, one of my first interactions with SwaggerHub was using the generate Server/Client functionality. I’ve used it as a reference point when attempting to learn other languages and when starting projects of my own. From that point of view, it’s an advantage as it helps form a key piece of SwaggerHub.
By supporting open source tooling, there are clear knock of benefits to a paid solution like SwaggerHub. The plugin for example enables customers to migrate into the platform faster than previously, thus improving their user experience. Other open source components such as the swagger parser form part of our backend architecture whereas the swagger editor is a major part of our frontend.
Do you see much collaboration between the open source and platform development efforts?
From my perspective, there is a fair amount of collaboration. Codegen for example, we may go to the open source team with issues and/or feature requests which in turn may or may not form a part the next release.
I’ve leaned on the open source team recently to help me ramp up on the open source standards in terms of development, PR’s, release process, documentation etc. It’s been a learning experience but a good one!
We see a lot of our users and customers really starting to take to heart the idea of a design-first approach to development (writing and updating an OAS to plan changes to a service before development). Any thoughts on design first, or the balance that teams strike between code and design first?
The concept of API design prior to development was one I didn’t pay too much heed to prior to joining Smartbear. When developing an API, I would regularly jump straight into my controller class and create or update endpoints with changes being communicated to the client at a later stage! I now see the value on the design first approach and would approach any API with a design-first attitude.
We use the design first principle when defining communication between the SwaggerHub backend and frontend. Work is done together to define what is required, what’s best practice and what is achievable. The API once defined acts as a contract between the developers who are developing both backend and frontend. When that contract is followed, neither are in for any unforeseen surprises. Using SwaggerHub’s Auto-mock, frontend developers can start development prior to the backend being implemented, which unblocks and speeds up development.
Like writing code, I feel it’s probably best to write a little, test, refactor and repeat. The complete solution will evolve naturally as part of this process. Any refactoring won’t require a total rewrite which will cause major delays (and heartache!).
We recently ran our State of API survey and one of the big takeaways was how microservices are starting to change organizations development efforts and the number of services that are being produced. Do you think there’s a correlation between the increasing popularity of OpenAPI/Swagger tools and organizations going through this ‘digital transformation’?
I do! We use SwaggerHub to great effect. As I mentioned we define our API definitions and store those in SwaggerHub. As we have quite a number, it’s good to centralise them in one location and be able to view them with a nice UI like SwaggerHub.
We use SwaggerHub combined with Codegen to generate API clients during our build process. This removes the need to maintain custom written clients and ensures our requests match what is expected. This speeds up development and allows us to write the underlying business logic instead of writing boilerplate client logic.
I’ve recently started working with a 3rd party API. Their documentation uses Swagger which was a pleasant surprise and allowed me to get stuck into forming a client immediately. I’m looking forward to seeing what SwaggerHub has in store for later releases and hoping to play a big part in that. In terms of the plugin, we’re continuing to add other SCM’s support and improving it wherever possible.
For more information about the SwaggerHub Build Plugin – be sure to explore the repository.
If you are interested in learning more about the SwaggerHub platform or speaking to a Swagger specialist about migrating, schedule a call today!