Runscope API Monitoring    Learn More →

Posts filtered by tag: openapi

How to Merge OpenAPI Definition Files

By Heitor Tashiro Sergent on .


I recently saw a Twitter thread that started with a simple question: how to combine multiple OpenAPI 3 definition files back together? One of the answers on that Twitter thread came from Mike Ralphson, and he pointed out that speccy, an open-source project, could help with that.

Now, you might ask yourself, why would someone want to merge an OpenAPI definition file back together? Isn't the point of separating it into multiple files to have better organization? Well, merging a definition file back together into a single one can be useful if you have tooling that doesn't support definition files with references and requires a single one to be uploaded, whether that is for documentation tooling, a UI definition editor, or maybe for API Gateway support.


speccy is an open-source project written in Node.js, that allows the user to lint, merge, and visualize an OpenAPI definition in a human-readable format.

For our purposes, we're just going to focus on the merging aspect of it.

How to Merge OpenAPI 3 Files

To use speccy, first we need to have Node.js installed in our machine. You can either download it from the Node.js website, or open the terminal and run:

curl "${VERSION:-$(wget -qO- | sed -nE 's|.*>node-(.*)\.pkg</a>.*|\1|p')}.pkg" > "$HOME/Downloads/node-latest.pkg" && sudo installer -store -pkg "$HOME/Downloads/node-latest.pkg" -target "/"

Then, we can install speccy by opening the terminal and running:

npm install -g speccy@0.8.7

And finally, still in the terminal, go to the directory where your OpenAPI definition files are and run:

speccy resolve spec.yaml -o spec-output.yaml

`resolve` is the command to merge definition files back into one. It's followed by the path to the main definition file that includes references to other files you wish to merge. Next, we add the option flag -o to output the resulting definition to a new file named spec-output.yaml.

If you want to test this on a definition file that's broken up into separate files but you don't have one at the moment, you can use this example I set up using the Pet Store example:

And if you're curious about the way I split up this OpenAPI definition, I used this great blog post by Jack Skinner as a reference: Maintaining large design-first API specs.

And you're all set.

Note: you might have noticed that we are using a specific version of speccy, 0.8.7, in the install command. At the time of writing, there was a known issue with the latest version where the output flag for the resolve command was not working. I would recommend using the latest version if that bug has been fixed. And always be kind to open-source maintainers. :)

Categories: openapi, tutorial

Using OpenAPI to Improve Daily Life as an Engineering Team

Using OpenAPI to Improve Daily Life as an Engineering Team

By Mike Mackrory on .

In part one of this series, we talked about the OpenAPI framework and the concept of API-First development. In this second and final part, I’d like to demonstrate how this framework and these principles can be applied in the day-to-day functioning of a technology organization to increase velocity and improve the effectiveness of your development activities.

I’ll start by describing the problems we faced as an organization and how we used these principles to not only solve those problems but also improve how we were able to develop applications. As with any process, our implementation had some hiccups, but we learned valuable lessons. Through sharing these lessons, I’m hopeful that I can enable more people to be successful if they decide to implement an API-First method in their organizations.

Read More →

Categories: apis, openapi, swagger

Getting Started with the OpenAPI Specification

Getting Started with the OpenAPI Specification

By Mike Mackrory on .

When I’m not writing articles, I work for a large software organization. We have lots of engineering teams, all of which contribute to specific elements of a sophisticated, versatile and highly available commerce platform. We’ve chosen an API-First approach to accelerate development and enhance collaboration between domains.

Because APIs are so central to how our software runs, documenting our APIs is essential for making sure that everyone across our large IT organization understands what is going on. That’s why we use OpenAPI to help document API specifications.

In this article, I’m going to introduce you to the OpenAPI specification and API-First development principles. In a subsequent article, I’ll describe how our teams use the API-First approach to support our engineering endeavors. […]

Read More →

Categories: swagger, openapi, apis

Building Serverless Applications with an API-First Approach

Building Serverless Applications with an API-First Approach

By Mike Mackrory on .

In this article, we’re going to be examining what an API-first design strategy looks like when it comes to developing serverless applications. We’re going to talk about why this approach is essential, what are its benefits, and walk through a simple example of creating a basic OpenAPI spec using SwaggerHub, and deploying it using AWS Lambda.

Start with the End in Mind

As developers and engineers, we like to solve problems. Give us an idea of what needs to be fixed or produced, and we’ll have our IDE open and our fingers tapping out magical code before you finish speaking.

Fast innovation is a good thing. In this case, however, there is a downside: You’ll end up with an API that is “designed” and “documented” as an afterthought and made to fit the code. This approach may require additional work […]

Read More →

Categories: swagger, openapi, apis, serverless

10 Steps to a Painless API Release

10 Steps to a Painless API Release

By James Higginbotham on .

James Higginbotham, Executive API Consultant, shares his API and product release insights with a list of 10 essential steps to improve the next release of your API.

If you're interested in being a part of our next series, fill out this short form and we'll get in touch with you for our next run.

It is exciting to release something new. The thrill of seeing an idea to completion is always an exciting time for software teams. But how do you know when an API is ready to release? What if you missed something that could result in increased support emails and calls? What if you broke existing internal or 3rd-party integrations?

This article provides a 10-point checklist to help ensure your next API release is as smooth as possible.

1. Did you verify that we met stakeholder needs?

You may design the most beautiful, amazing API ever imagined. It might cause API designers to weep at its beauty. But, if it doesn't solve the problems of your stakeholders, you have failed to deliver a well-designed and useful API. [...]

Read More →

Categories: apis, community, featured guest series, openapi

How to Sync your OpenAPI Schema in Stoplight with GitHub and Runscope

How to Sync your OpenAPI Schema in Stoplight with GitHub and Runscope

By Glen Semino on .

This is a post from our Featured Guest Series! Glen Semino shows how to combine Stoplight and GitHub APIs with Runscope to keep your OpenAPI Schema always versioned and up to date.

If you're interested in sharing your knowledge on our blog, check out our Featured Guest Series page for more details.

About a month ago after I and part of the SYNQ team attended the APIDays SF conference, we reflected on what we had learned at the conference. One of the things we realized was that our API spec documentation needed quite a bit of improvement. And among the tools discussed in the conference was Stoplight, which helps one design, document, mock, and test APIs. 

We decided to give Stoplight a try to rewrite and edit our API spec. Once we started, I noticed that I was often manually syncing our Open API spec (OAS) file that Stoplight generates with our GitHub repo. I wanted a way to automate this process so that regardless of what gets edited/changed in Stoplight, Stoplight and GitHub are always in sync. 

This is where Runscope came to save the day. Using the export function Stoplight offers in addition to GitHub’s API, I was able to automate syncing our Stoplight OAS spec file with our GitHub repo every minute using Runscope. In this tutorial, we're going to walk through this workflow step-by-step so that you can do it too!

The Setup

These are the things you will need to do to create the necessary API requests in Runscope to automate the syncing process...

Read More →

Categories: code samples, howto, monitoring, openapi

Everything is going to be 200 OK®