Runscope API Monitoring    Learn More →

Posts filtered by tag: swagger

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

Tutorial - Converting your Swagger 2.0 API Definition to OpenAPI 3.0

Tutorial - Converting your Swagger 2.0 API Definition to OpenAPI 3.0

By Heitor Tashiro Sergent on .

At the end of July, the OpenAPI Specification 3.0.0 was finally released by the Open API Initiative. It's a major release, and after 3 years in the making, it brings about a lot of improvements over the 2.0 specification, making it possible to create definitions for a broader range of APIs.

What's New in OpenAPI 3.0.0

There're a lot of new features that were added to this version, such as...

Read More →

Categories: apis, tutorial, swagger, openapi

OpenAPI / Swagger Resource List for API Developers

By Heitor Tashiro Sergent on .

The OpenAPI Specification, formerly known as Swagger Specification, is a simple yet powerful way of describing RESTful APIs, in a machine and human readable format, using JSON or YAML. It has a large ecosystem of tools that can help you design, build, document, test, and visualize your APIs.

Crafting good APIs is no easy task. OpenAPI brings a lot of benefits to this process, whether you approach it from a design-first or code-first perspective. The ecosystem of tools can help you generate interactive documentation, SDKs for your APIs in multiple languages, and server stubs.

But getting started with OpenAPI can be challenging. Figuring out how to start writing a spec from the ground up or for existing APIs, which tools, cloud providers, and frameworks support the specification, the differences between 1.2, 2.0, and the upcoming 3.0 versions, and finding open-source generators for your SDKs are only a few of the questions you can run into.

That's why we decided to aggregate the best resources in a single place, and hopefully, guide you on this journey in implementing and making the most of your OpenAPI specification [...]

Read More →

Categories: api ecosystem, openapi, swagger

Everything is going to be 200 OK®